# Chapter 16

| # Console Integration

> This chapter covers the following topics:

- Extending the Console--page 327
- Integrating Sun Management Center Software With Other Management Tools--page 333
- Compilation and makefile Guidelines--page 342

> This chapter contains instructions and examples for integrating the Sun Management Center Console with other applications. Two significant aspects of integration are considered:

- enabling the Console to launch user-specific applications
- enabling other management tools to utilize features provided by the Console

> This chapter covers the following topics:

- Extending the Console--page 327
  - Integration Levels--page 328
  - Configuration Files--page 329
  - Update Utilities--page 332
- Integrating Sun Management Center Software With Other Management Tools--page 333
- Compilation and makefile Guidelines--page 342

## Extending the Console

> The Sun Management Center Console can be extended to include additional functionality as users deem necessary. Support for the integration of applications providing such functionality is through two configuration files
> (`console-tools.cfg` and`console-host-apps.cfg`) and two utility scripts (`es-tool` and `es-apps`) that update the environment based on the content of the configuration files. Integration levels and syntax for entries in the configuration files are discussed in this section.

> The general process for extending the Console is as follows:

1. Place the Java class files or the `.jar` files for the user applications in the standard Sun Management Center location:
   `
   /opt/SUNWsymon/apps/classes/`
   If there are any auxiliary files, such as, property files or images, they should also be placed in either this directory or a `.jar` file.
2. Select the appropriate integration level to determine the appropriate configuration file and utility.
3. Modify the appropriate configuration file to describe the desired extension.
4. Run the appropriate update utility.
5. Restart the Console. Depending upon your site's configuration, it may be necessary to restart the Server as well.

### Integration Levels

> Sun Management Center supports the following levels of application integration:

- External Java application with no API or access to the current host selection: This level applies to external, stand-alone applications written in Java that the user wishes to launch from the Console. The application must be written in Java; non-Java applications are accommodated by the `SMSystemCommand` Java wrapper class that executes other programs or shell scripts in a separate process. For a description of `SMSystemCommand`, refer to the section on "es-tool: Syntax for console-tools.cfg Entries".
  The application does not require any host selection context or Client API handle. The application has no further interaction with Sun Management Center once it has been launched. The name of the application (as specified in the `console-tools.cfg` file) will be appended to the Tools Menu in the Console below the standard menu items provided by the Sun Management Center. Support for this integration level is provided through the `console-tools.cfg` file and the
  `es-tool` update utility.
- External Java application with API and host selection context: This level applies to custom Java applications that the user wishes to launch from the Console. The application runs under the same JVM as the Console. The application requires a pre-authenticated Client API handle and additional global user information. The application may also require access to the host selection context. The name of the application (as specified in the `console-tools.cfg` file) will be appended to the Tools Menu in the Console below the standard menu items provided by the Sun Management Center. The GUI for the application is displayed in a separate window. Support for this integration level is provided through the `console-tools.cfg` file and the `es-tool` update utility.
- Internal Java application utilizing the host details context: This level applies to custom Java applications that the user wishes to launch for a particular host that has been selected in the Browser tab or the Topology display. The application requires access to the Host selection context. The name of the application (as specified in the `console-host-apps.cfg` file) will be added to the tree list displayed in the Applications tab in the Host Details window. The application may or may not have an associated GUI; if it does have a GUI, the GUI will be displayed within the Display portion of the Host Details window when the application is launched. Support for this integration level is provided through the `console-host-apps.cfg` file and the `es-apps` update utility.

> > Note - User applications may wish to implement the `SMApp` interface or extend the `SmAppBase` class in order to obtain access to the agent information. Refer to the `javadocs` for specific information.

### Configuration Files

> The `console-tools.cfg` and `console-host-apps.cfg` files are plain text files that can be edited with any standard text editor. The files reside on the host on which the Server is running. The files may be modified at any time (including while the Console is running), but changes introduced by editing the files will not take effect until the appropriate update utility is run on the server host and the Console is restarted (depending upon site configuration, it may be necessary to restart the Server as well). Each file consists of a series of lines, each of which describes an application; blank lines and lines beginning with the pound sign `#' are ignored. Fields within each line are separated by commas `,'.

#### ``es-tool: Syntax for console-tools.cfg Entries

> Applications listed in the `/var/opt/SUNWsymon/cfg/console-tools.cfg` file are launched from the Tools menu in the Console main window. Each application is defined by a line with the following format:

>     menu_label,class [args]

> Entry fields are as follows:

- menu label -- the string that will appear in the Tools menu. The string can be either unlocalized or localized text. Unlocalized text can contain embedded spaces. Localized text must be specified as a property_file:key pair, where property_file is the name of the file containing the localizable messages for a particular locale, and key is the identifier used to locate the string that will appear in the Tools menu in the property file. Note that spaces are not allowed in the key. Refer to chapter 17 for a discussion of the syntax for the property file.
- class -- the fully qualified Java class name.
- args -- the list of arguments to the class.

> The example file below shows entries for three applications to be listed on the Tools menu: `Example GUI`, `telnet`, and `ftp`:

>     # Format:
>     # menu_label,class arguments
>     Example GUI,exampleApp.ExampleGUITool

>     Telnet,com.sun.symon.base.client.console.SMSystemCommand \
>     "/usr/openwin/bin/xterm -e telnet $host" "start telnet $host"

>     exampleApp.ExampleSystemCommand:ftp,exampleApp.ExampleSystemCommand \
>     "/usr/openwin/bin/xterm -e ftp $host" "start ftp $host"

> A special built-in Java wrapper class `SystemCommand` is provided to enable the user to execute an arbitrary shell command. This class takes two arguments. The first argument is the shell command to execute. If a program name is specified, a full path should be given. If there are embedded spaces, the entire shell command should be enclosed in double quotes. The second argument is the command to run if on a Microsoft Windows client, in which case the first argument is ignored.

>     com.sun.symon.base.client.console.SystemCommand \

>     shell_command windows_command

> Variable substitution is performed on the arguments if special variable references are present. The allowed variables are given below:

>     $host

>     replaced with currently selected agent host name

>     $port

>     replaced with currently selected agent port number

#### es-apps: Syntax for console-host-apps.cfg Entries

> Applications listed in the `/var/opt/SUNWsymon/cfg/console-host-apps.cfg` file are launched from the Applications tab in the Host Details window. Each application is defined by a line with the following format:

>     menu_label,class,[args],[help]

> Entry fields are as follows:

- menu label -- the string that will appear in the Applications tab. The string can be either unlocalized or localized text. Unlocalized text can contain embedded spaces. Localized text must be specified as a property_file:key pair, where property_file is the name of the file containing the localizable messages for a particular locale, and key is the identifier used to locate the string that will appear in the Applications tab in the property file. Note that spaces are not allowed in the key. Refer to chapter 17 for a discussion of the syntax for the property file.
- class -- the fully qualified Java class name.
- args (optional) -- the list of arguments to the class.
- help (optional) --the help key.
  This is specified in one of the forms described in the "Help Key Usage".

> Help Key Usage

- The help key is specified in one of the following forms.
  - `:file pair
    `The first form is a key`:file pair`, where key is a unique string that associates the help file with the application, and file is the name of the HTML file containing the help for the application. (Note that this is only the file name, not the full path of the HTML file, and that this HTML help file must be installed on the Sun Management Center server.) The directory where you need to install this file is:

        /opt/SUNWsymon/lib/locale/<lang>/help

    This means that file must be based on this root directory. For example, if you specify a file called, /mysubdir/myhelf.html, the file needs to be placed in:

        /opt/SUNWsymon/lib/locale/<lang>/help/mysubdir/myhelp.html

  - `:url
    `The second form is `:url`, where url is any URL specification.
  - `:file
    `The third form is `:file`, where file is a fully qualified pathname to a file
    (`/mydirectory/myfile.html`). This will load the specified file from the specified location. The file must be installed on the console machine.

> > Note - In the case where there are no arguments to the class but you wish to specify a help file, you must still indicate the (empty) arguments field with a command.
> > Note also that the Help files are installed on the Help Server machine. This machine may or may not be the same machine that the Sun Management Center server is installed upon, depending on how you set up your network and Sun Management Center. Even though the help files themselves are installed on the Help Server, you still execute the `es-chelp`, `es-apps`, and other applicable commands on the Sun Management Center server.

> The example file below lists two hypothetical applications. The first application has arguments but no help file; the second application has a help file but no arguments.

>     # example 1: arguments but no help file
>     example.ExampleModuleApp1:ExampleApp1, example.ExampleApp1, arg1 arg2 arg3
>     #
>     # example 2: help file but no arguments
>     example.ExampleModuleApp2:ExampleApp2, example.ExampleApp2, key:file

### Update Utilities

> The integration configuration files can be edited at any time; however, in order for the changes specified in the file to be propagated to the Server, the appropriate update utility must be run on the Server host. For each configuration file, there is a corresponding update utility: for the `console-tools.cfg` file, the update utility is `/opt/SUNWsymon/sbin/es-tool`; for the `console-host-apps.cfg` file, the update utility is `/opt/SUNW/symon/sbin/es-apps`. If you wish to use an alternative configuration file, you can specify the name as an argument to the utility

> The list of user applications is generated from these configuration files each time these scripts are run. Removing an entry from a configuration file will cause it to be also removed from the list.

## Integrating Sun Management Center Software With Other Management Tools

> Sun Management Center software is an enterprise-wide management solution for managing Sun platforms. Any other management solution that wants to use Sun Management Center software for management of a Sun platform can achieve this using a utility Bean that is provided as a part of the Sun Management Center Sun Management Center Developer Environment Manual . This Bean is a Sun Management Center Object Details window that can display details without requiring the user to navigate in the topology view in the Sun Management Center main console.

> The class specification of this Bean is:

>     package name: com.sun.symon.apps.details.hostdetailsBean
>     Class HostdetailsBean
>     java.lang.Object
>     	|
>     +--com.sun.symon.tools.hostdetailsBean.HostdetailsBean
>     public class HostdetailsBean extends java.lang.Object

> HostdetailsBean is a Bean that launches an Sun Management Center Host Details window for a given Sun Management Center agent system monitored by a specified Sun Management Center server. This Bean uses classes and configuration files that are part of the Sun Management Center installation and therefore work only when the Sun Management Center console and server installation exists. Note that the Bean must be started in a separate thread.

| ### To Invoke the HostDetailsBean

| 1. | Instantiate a HostdetailsBean object:
    	HostdetailsBean theBean = new HostdetailsBean();

| 2. | Initialize Bean parameters:
    	theBean.init(String,String,String,String,String,null);

| 3. | Optionally, subscribe for PropertyChangeEvents from the Bean :
    theBean.addPropertyChangeListener(this);

| 4. | Optionally, set the exit() method of the Bean:
    theBean.setExitAction(Object, String, Object[])

| 5. | Launch hostdetails:
    theBean.doLaunchHostdetails();

> PropertyChangeEvent events are fired when exceptions from the Sun Management Center client API are caught. It is the responsibility of the Bean user to listen for these events and take appropriate action. Also, PropertyChangeEvents are fired to relay informational (status) messages that could be reflected in a GUI or used to control the Bean environment.

### Field Summary

    static java.lang.String ERROR_NO_TARGET
    	Bounded property value indicating target system not found
    static java.lang.String HOSTDETAILS_ERROR
    	 Bounded property-name for notification of Exception conditions
    static java.lang.String HOSTDETAILS_STATUS
    	Bounded property-name for notification of status conditions
    static java.lang.String SECURITY_SCHEME
        security scheme
    static java.lang.String STATUS_AUTHENTICATION_OK
        Bounded property value indicating hostdetails is exiting without error
    static java.lang.String STATUS_CONNECTION_OK
       Bounded property value indicating hostdetails is exiting without error
    static java.lang.String STATUS_EXITING_OK
    	Bounded property value indicating hostdetails is exiting without error
    static java.lang.String STATUS_STARTUP_OK
    	Bounded property value indicating hostdetails started okay

### Constructor Summary

    HostdetailsBean()

### Method Summary

>     void
>     addPropertyChangeListener(java.Beans.PropertyChangeListener listener)

> Convenience method for subscribing an object to PropertyChangeEvents. This must be done after init() is called.

>     void doExitAction()

> Bean exit method.

>     void doLaunchHostdetails()

> This method communicates with the Sun Management Center server and launches the Hostdetails window.

>     void init(java.lang.String sName, int sPort,
>     java.lang.StringtargetHost, java.lang.String user,
>     java.lang.String pass, java.lang.String key)

> This method initializes values needed for proper operation of the Bean.

>     void propertyChange(java.Beans.PropertyChangeEvent evt)

> This method is responsible for notifying subscribers of property changes within the Bean.

>     void
>     removePropertyChangeListener(java.Beans.PropertyChangeListener
>     listener)

> Convenience class for removing an object subscription to PropertyChangeEvents. This must be done after init() is called.

>     void setExitAction(java.lang.Object target, java.lang.String
>     method, 		java.lang.Object[] myArgs)

> This method allows specification of an alternate method to execute when the hostdetails window is closed.

>     void setHostname(java.lang.String host)

> Mutator method for setting the Sun Management Center server hostname.

>     void setHostport(int port)

> Mutator method for setting the Sun Management Center server port.

>     void setPassword(java.lang.String pass)

> Mutator method for setting the Sun Management Center server password.

>     void setPublicKey(java.lang.String key)

> Mutator for Sun Management Center server public crypto key. If set to null, defaults to an internal value.

>     void setTarget(java.lang.String targ)

> Mutator method for setting the target system.

>     void setUser(java.lang.String user)

> Mutator method for setting the Sun Management Center server login username.

### Field Detail

>     public static final java.lang.String HOSTDETAILS_ERROR

> Bounded property-name for notification of exception conditions

>     public static final java.lang.String HOSTDETAILS_STATUS

> Bounded property-name for notification of status conditions

>     public static final java.lang.String STATUS_STARTUP_OK

> Bounded property value indicating hostdetails started okay

>     public static final java.lang.String STATUS_EXITING_OK

> Bounded property value indicating hostdetails is exiting without error

>     public static final java.lang.String STATUS_CONNECTION_OK

> Bounded property value indicating hostdetails is exiting without error.

>     public static final java.lang.String STATUS_AUTHENTICATION_OK

> Bounded property value indicating hostdetails is exiting without an error.

>     public static final java.lang.String ERROR_NO_TARGET

> Bounded property value indicating target system not found

>     public static final java.lang.String SECURITY_SCHEME

> Security scheme.

>     public static final boolean WANT_ENCRYPTION

> Encryption

### Constructor Detail

>     public HostdetailsBean()

> Empty constructor for Bean compliance

### Method Detail

>     public void init(java.lang.String sName, int sPort,
>     java.lang.String targetHost, java.lang.String user,
>     java.lang.String pass, java.lang.String key)

> This method initializes values needed for proper operation of the Bean. Mutators are available for these fields in addition to this method.

> Parameters:

> `sName` - Hostname of the Sun Management Center server
> `sPort` - Port number used by the Sun Management Center server
> `targetHost` - Sun Management Center "label name" of the system to be displayed
> `user` - Sun Management Center server login name
> `pass` - Sun Management Center server password for above user
> `key` - Sun Management Center server public key (defaults if null)

>     public void setHostname(java.lang.String host)

> Mutator method for setting the Sun Management Center server hostname.

> Parameters:

> `host` - Sun Management Center server hostname

>     public void setHostport(int port)

> Mutator method for setting the Sun Management Center server port.Parameters:

> `port` - Sun Management Center server port number (probably 2099)

>     public void setTarget(java.lang.String targ)

> Mutator method for setting the target system; that is, the system for which you would like hostdetails displayed.

> Parameters:

> `targ` - target system name, as known to Sun Management Center as "label name"

> This is not the same as hostname. It is the Sun Management Center label name.

>     public void setUser(java.lang.String user)

> Mutator method for setting the Sun Management Center server login username.

> Parameters:

> `user` - username for login to Sun Management Center server

>     public void setPassword(java.lang.String pass)

> Mutator method for setting the Sun Management Center server password.

> Parameters:

> `pass` - password for login to Sun Management Center server

>     public void setPublicKey(java.lang.String key)

> Mutator for Sun Management Center server public crypto key If set null, this will

> default to an internal value.

> Parameters:

> `key` - Sun Management Center server public key.

>     public void propertyChange(java.Beans.PropertyChangeEvent evt)

> This method is responsible for notifying subscribers of property changes within the Bean.

> Parameters:

> `evt` - PropertyChangeEvent to be fired

>     public void
>     addPropertyChangeListener(java.Beans.PropertyChangeListener
>     listener)

> Convenience method for subscribing an object to PropertyChangeEvents. This must be done after init() is called.

> Parameters:

> `listener` - a PropertyChangeListener to subscribe for events

>     public void removePropertyChangeListener(java.Beans.PropertyChangeListener listener)

> Convenience class for removing an object subscription to PropertyChangeEvents. This must be done after init() is called.

> Parameters:

> `listener` - PropertyChangeListener to remove from subscription list

>     public void doExitAction()

> Convenience method to do exit actions.

>     public void setExitAction(java.lang.Object
>     target,java.lang.String method, java.lang.Object[] myArgs)

> Throws

>     java.lang.IllegalArgumentException

1. This method allows specification of an alternate method to execute when the hostdetails window is closed. By default the Bean will call `System.exit(0)`.

> Parameters:

> target - Object which contains the method to be called
> method - Method name to be called
> argv - String array containing method arguments

> Throws:

>     java.lang.IllegalArgumentException

> if introspection/invocation would fail.

>     public void doLaunchHostdetails()

> Throws:

>     java.lang.IllegalStateException

> This method communicates with the Sun Management Center server and launches the Hostdetails window. If you did not initialize all fields correctly through `init()`, you may receive an IllegalStateException.

> Throws:

>     java.lang.IllegalStateException - if any required fields are null.

## Compilation and `makefile` Guidelines

> For compilation of JavaBeansTM, the Java `CLASSPATH` must be set. Typically the `CLASSPATH` should be set to the following:

>     ESROOT = /opt/SUNWsymon
>     CLASSPATH = \
>             $(ESROOT)/jclass/chart/lib/jcchart362J.jar:\
>             $(ESROOT)/classes/essrv.jar:\
>             $(ESROOT)/classes/esclt.jar:\
>             $(ESROOT)/classes/escon.jar:\
>             $(ESROOT)/classes/escom.jar:\
>             $(CLASSPATH)

> For an example of makefile, refer one the console examples under

>     /opt/SUNWsymon/sdk/examples/console

> ``

Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.