A set of services, collectively called the HATS Runtime Services, are provided as an interface to the HATS runtime, HATS rich client applications, and running application instances. Using this set of provided APIs is the recommended method of interaction with the HATS runtime, since you don't need to be concerned with the underlying details.
Table 11 describes the types of services provided. There is only one instance of the runtime service and client service per Eclipse environment, but there can be multiple instances of the application service (since multiple HATS rich client applications can be installed into an Eclipse environment) and the session service (since a user can start multiple sessions, or application instances).
| Service | Description | Scope |
|---|---|---|
| Runtime | Provides runtime-related services, such as runtime initialization, creating new client sessions, providing access to the connection manager and application manager classes. | One per Eclipse environment. |
| Application | Provides interface for retrieving information about the HATS rich client application. | One per HATS rich client plug-in application. |
| Client | Provides interface for retrieving information about a client or user. | One per Eclipse environment. |
| Session | Provides interface for interacting with HATS runtime on behalf of a particular application instance / host connection. | One per running application instance. |
import java.util.Collection; import java.util.Iterator; import com.ibm.hats.rcp.runtime.RcpRuntimePlugin; import com.ibm.hats.runtime.services.IApplicationService; import com.ibm.hats.runtime.services.IClientService; import com.ibm.hats.runtime.services.IRuntimeService; import com.ibm.hats.runtime.services.IServiceManager; import com.ibm.hats.runtime.services.ISessionService; import com.ibm.hats.runtime.services.ServiceType;
All services are created and maintained by a single service manager (which implements the com.ibm.hats.runtime.services.IServiceManager interface). Service objects should not be constructed outside of the service manager. The following code sample shows how to access the service manager:
IServiceManager serviceManager = RcpRuntimePlugin.getDefault().getServiceManager();
Table 12 identifies the methods that can be called by the IServiceManager object.
| Method | Description |
|---|---|
| addServiceManagerListener(ServiceManagerListener) | Adds a listener to this service manager. |
| removeServiceManagerListener(ServiceManagerListener) | Removes a listener from this service manager. |
| getApplicationService(String) | Returns the IApplicationService corresponding to the specified application plug-in ID. |
| getClientService(String) | Returns the IClientService corresponding to the specified client ID (in the rich client, the client ID is always the value of RcpRuntimeService.rcpClientId). |
| getRuntimeService() | Returns the IRuntimeService for the environment. |
| getSessionService(String, String, String) | Returns the ISessionService corresponding to the specified client ID, application plug-in ID, and view ID. |
| getServiceIDs(ServiceType) | Returns a set of IDs corresponding to services managed by this service manager with the specified service type getServiceEntryCount(ServiceType). |
| getServiceEntryCount(ServiceType) | Returns the number of services managed by this service manager with the specified type. |
See the com.ibm.hats.runtime.services.IServiceManager API for more information.
The runtime service, which implements the com.ibm.hats.runtime.services.IRuntimeService interface, provides methods for interacting with the HATS runtime. Most of the methods provided on this service should not be called directly, but are made public so other components of the HATS runtime can communicate. The runtime service object for an application should be retrieved from the service manager. Sample code to retrieve the runtime service:
IRuntimeService runtimeService =
serviceManager.getRuntimeService();
The following methods can be called by the runtime service:
| Method | Description |
|---|---|
| getConnectionManager() | Returns the default ConnMgr instance. |
| getServiceManager() | Returns the service manager that instantiated this service. |
The application service, which implements the com.ibm.hats.runtime.services.IApplicationService interface, provides methods for retrieving information related to a HATS rich client application. Each HATS rich client application plug-in installed and enabled in the Eclipse environment will have an associated IApplicationService object. The application service object for an application should be retrieved from the service manager. Sample code to retrieve the application service:
IApplicationService applicationService =
serviceManager.getApplicationService("myPluginId");The getApplicationService(String) method will return null if the specified application ID is invalid or the plug-in failed to start.
Table 14 identifies the methods that can be called by the IApplicationService object.
| Method | Description |
|---|---|
| getApplication() | Returns an Application object which contains information about the application. This object is not guaranteed to be synchronized with the application.hap file, and the use of the object returned by this method should only be used to retrieve information. Do not use this object to alter any settings. |
| getApplicationId() | Returns the application identifier. |
| getConfig() | Returns the configuration. |
| getRuntimeService() | Returns the runtime service. |
| getServiceManager() | Returns the service manager that instantiated this service. |
The client service, which implements the com.ibm.hats.runtime.services.IClientService interface, provides methods for retrieving information related to the client service. Sample code to retrieve the client service:
IServiceManager serviceManager = RcpRuntimePlugin.getDefault().getServiceManager();
IClientService clientService = serviceManager.getClientService("theClientId");
Table 15 identifies the methods that can be called by the IClientService object.
The session service, which implements the com.ibm.hats.runtime.services.SessionService interface, provides methods for interacting with an instance of a HATS rich client application. Each running application instance, for example, a transformation view instance, has an associated session service. There is a one-to-one mapping between a transformation view instance and a session service.
Sample code for retrieving the complete collection of session services:
IServiceManager serviceManager =
RcpRuntimePlugin.getDefault().getServiceManager();
Collection sessionServices =
serviceManager.retrieveServiceEntries( ServiceType.SESSION );
Iterator itSessionServices =
sessionServices.iterator();
while ( itSessionServices.hasNext() )
{
ISessionService aSessionService =
(ISessionService) itSessionServices.next();
// Your custom code goes here
}
Table 16 identifies the methods that can be called by the ISessionService object representing an instance of an application.
The associated ISessionService object for a transformation view can be retrieved by calling the getSessionService() method on the view. This method is provided by the ITransformationView interface, which is implemented by the base TransformationView class.
By using the Runtime Services APIs, HATS transformation views, or HATS rich client applications, can communicate with other Eclipse UI views, or non HATS rich client applications. This communication can be either incoming or outgoing with respect to the HATS application. Incoming communication is defined as a HATS rich client session receiving data or commands from an entity external to HATS. Outgoing communication is defined as a HATS rich client session sending data or commands to an external entity. This functionality enables pertinent data to be retrieved from multiple sources and displayed in a single view. Therefore, the HATS rich client application can either be the view receiving and displaying data from other Eclipse rich client applications or the application providing data to one or more Eclipse rich client applications for display.
In the following scenario, assume that you have a host application that takes a flight number for input and displays information about that flight. This application has been transformed into a HATS RCP application. Another Eclipse RCP-based application takes reservation information including the flight number. When the flight number is entered into this application, it can be transmitted to the HATS RCP application causing the HATS view to be updated with information for that flight number. The following is a code example for this scenario:
IServiceManager serviceManager = RcpRuntimePlugin.getDefault().getServiceManager();
IClientService clientService = serviceManager.getClientService("theClientId");
/*--------------------------------------------------------------------------------
//
// Provides an example of a HATS application receiving information from another
// application. This example cannot be executed directly but is provided to
// highlight the approach required to achieve this functionality.
//
// @param Flight number from GUI as a Java String. This value cannot be
// <code>null</code>.
//
*///------------------------------------------------------------------------------
public void inboundToHATSApplication( String flightNumber )
{
// Save flight number from GUI
Properties params = new Properties();
params.setProperty( "fltNum", flightNumber );
// Get the service manager from singleton plug-in instance.
IServiceManager serviceManager =
RcpRuntimePlugin.getDefault().getServiceManager();
// This will be the plug-in session we use to play our macro
ISessionService aSessionService = null;
// Find the correct HATS plug-in session
Collection sessionServices =
serviceManager.retrieveServiceEntries( ServiceType.SESSION );
Iterator itSessionServices = sessionServices.iterator();
while ( itSessionServices.hasNext() )
{
aSessionService = (ISessionService) itSessionServices.next();
// Assumes the first instance of the HATS plug-in called "myApp"
// is the one we want.
if ( "myApp".getApplicationId().equals( aSessionService ) )
{
break;
}
}
// Refer to documentation to see how to launch an RCP plug-in instance if
// one is not already launched
if ( aSessionService != null )
{
// Really should check the state in a limited-time loop,
// but let's assume we can go ahead
if ( aSessionService.getSessionServiceState().isOperational() )
{
// Ask HATS session service to play the macro with the fltNum
// from our GUI
// Assumes that the macro can start from current screen or from
// the results screen.
aSessionService.playMacro( "displayFlightInfo", params );
}
}
}
/*---------------------------------------------------------------------------------
//
// Host Access Transformation Services technology
//
// Module Name: RuntimeServicesExamples.java
//
// Description: Provides java code samples for accessing HATS Rich Client Program
// Runtime Services.
//
*///-------------------------------------------------------------------------------
package com.ibm.hats;
import java.util.Collection;
import java.util.Iterator;
import com.ibm.hats.rcp.runtime.RcpRuntimePlugin;
import com.ibm.hats.runtime.services.IApplicationService;
import com.ibm.hats.runtime.services.IClientService;
import com.ibm.hats.runtime.services.IRuntimeService;
import com.ibm.hats.runtime.services.IServiceManager;
import com.ibm.hats.runtime.services.ISessionService;
import com.ibm.hats.runtime.services.ServiceType;
//---------------------------------------------------------------------------------
/** <code><B>
* Class Name: </B> RuntimeServicesExamples <B><BR>
* Class Type: </B> Normal <B><BR>
* Base Class: </B> None <B><BR>
* Intf Class: </B> None <B><BR>
* Description: </code></B> Rich Client Program Runtime Services java code samples.
*///-------------------------------------------------------------------------------
public class RuntimeServicesExamples
{
//-----------------------------| Constants |-----------------------------------
//-----------------------------| Variables |-----------------------------------
//-----------------------------------------------------------------------------
/**
* The default constructor.
*///---------------------------------------------------------------------------
public RuntimeServicesExamples()
{
super();
}
//-----------------------------------------------------------------------------
/**
* Provides an example of accessing each application service.
*///---------------------------------------------------------------------------
public void accessApplicationService()
{
Collection applicationServices = this.retrieveApplicationServices();
Iterator itApplicationServices = applicationServices.iterator();
while ( itApplicationServices.hasNext() )
{
IApplicationService aApplicationService = (IApplicationService)
itApplicationServices.next();
// Custom code goes here
}
}
//-----------------------------------------------------------------------------
/**
* Provides an example of accessing each client service. Currently, there is
// only one.
*///---------------------------------------------------------------------------
public void accessClientService()
{
Collection clientServices = this.retrieveClientServices();
Iterator itClientServices = clientServices.iterator();
while ( itClientServices.hasNext() )
{
IClientService aClientService = (IClientService)
itClientServices.next();
// Custom code goes here
}
}
//-----------------------------------------------------------------------------
/**
* Provides an example of accessing each runtime service. Currently, there is
// only one.
*///---------------------------------------------------------------------------
public void accessRuntimeService()
{
Collection runtimeServices = this.retrieveRuntimeServices();
Iterator itRuntimeServices = runtimeServices.iterator();
while ( itRuntimeServices.hasNext() )
{
IRuntimeService aRuntimeService = (IRuntimeService)
itRuntimeServices.next();
// Custom code goes here
}
}
//-----------------------------------------------------------------------------
/**
* Provides an example of accessing each session service.
*///---------------------------------------------------------------------------
public void accessSessionService()
{
Collection sessionServices = this.retrieveSessionServices();
Iterator itSessionServices = sessionServices.iterator();
while ( itSessionServices.hasNext() )
{
ISessionService aSessionService = (ISessionService)
itSessionServices.next();
// Custom code goes here
}
}
//-----------------------------------------------------------------------------
/**
* Retrieve the client service.
*
* @return The client service.
*///---------------------------------------------------------------------------
public IClientService getClientService( final String clientId )
{
return this.getServiceManager().getClientService( clientId );
}
//-----------------------------------------------------------------------------
/**
* Retrieve the runtime service.
*
* @return The runtime service.
*///---------------------------------------------------------------------------
public IRuntimeService getRuntimeService()
{
return this.getServiceManager().getRuntimeService();
}
//-----------------------------------------------------------------------------
/**
* Retrieve the service manager.
*
* @return The service manager.
*///---------------------------------------------------------------------------
public IServiceManager getServiceManager()
{
return RcpRuntimePlugin.getDefault().getServiceManager();
}
//-----------------------------------------------------------------------------
/**
* Provides an example of retrieving a Collection of current application
* service objects.
*
* @return A Collection of current application service objects.
*///---------------------------------------------------------------------------
public Collection retrieveApplicationServices()
{
IServiceManager manager = this.getServiceManager();
Collection applicationServices = manager.retrieveServiceEntries(
ServiceType.APPLICATION );
return applicationServices;
}
//------------------------------------------------------------------------------
/**
* Provides an example of retrieving a Collection of current client service
* objects. Currently, there is only one.
*
* @return A Collection of current client service objects.
*///----------------------------------------------------------------------------
public Collection retrieveClientServices()
{
IServiceManager manager = this.getServiceManager();
Collection clientServices = manager.retrieveServiceEntries(
ServiceType.CLIENT );
return clientServices;
}
//-----------------------------------------------------------------------------
/**
* Provides an example of retrieving a Collection of current runtime service
* objects. Currently, there is only one.
*
* @return A Collection of current runtime service objects.
*///---------------------------------------------------------------------------
public Collection retrieveRuntimeServices()
{
IServiceManager manager = this.getServiceManager();
Collection runtimeServices = manager.retrieveServiceEntries(
ServiceType.RUNTIME );
return runtimeServices;
}
//-----------------------------------------------------------------------------
/**
* Provides an example of retrieving a Collection of current session service
* objects.
*
* @return A Collection of current session service objects.
*///---------------------------------------------------------------------------
public Collection retrieveSessionServices()
{
IServiceManager manager = this.getServiceManager();
Collection sessionServices = manager.retrieveServiceEntries(
ServiceType.SESSION );
return sessionServices;
}
//-----------------------------------------------------------------------------
/**
* Provides an example of turning off border rendering for all input fields.
*
*
*///---------------------------------------------------------------------------
public int getControlClassStyle(class controlClass)
{
if (controlClass.equals(Text.class))
{
return 0;// super.getControlClassStyle(controlClass);
}
else
{
return super.getControlClassStyle(controlClass);
}
}
The following example shows how you can use the service manager to enable your plugin to listen for 3270 print job events. These changes are made to the RCP application plugin class:
package printExample;
import java.util.HashSet;
import org.eclipse.jface.resource.ImageDescriptor;
import org.osgi.framework.BundleContext;
import com.ibm.hats.rcp.runtime.RcpRuntimePlugin;
import com.ibm.hats.rcp.ui.AbstractRcpApplicationPlugin;
import com.ibm.hats.runtime.ApplicationSpecificInfo;
import com.ibm.hats.runtime.ClientSpecificInfo;
import com.ibm.hats.runtime.IPrintJobManagerChangeListener;
import com.ibm.hats.runtime.PrintJob;
import com.ibm.hats.runtime.PrintJobManager;
import com.ibm.hats.runtime.PrintResourceHandler;
import com.ibm.hats.runtime.PrintSpecificInfo;
import com.ibm.hats.runtime.events.CommandEvent;
import com.ibm.hats.runtime.events.ISessionServiceListener;
import com.ibm.hats.runtime.events.ServiceManagerEvent;
import com.ibm.hats.runtime.events.ServiceManagerListener;
import com.ibm.hats.runtime.events.StateChangeEvent;
import com.ibm.hats.runtime.services.IService;
import com.ibm.hats.runtime.services.IServiceManager;
import com.ibm.hats.runtime.services.ISessionService;
import com.ibm.hats.util.StateType;
/**
* The activator class controls the plug-in life cycle
*/
public class PrintExamplePlugin extends AbstractRcpApplicationPlugin implements
ServiceManagerListener, ISessionServiceListener,
IPrintJobManagerChangeListener
{
// The plug-in ID
public static final String PLUGIN_ID = "PrintExample";
// The shared instance
private static PrintExamplePlugin plugin;
// The service manager
private IServiceManager serviceManager = null;
// The print managers we are listeners for
private HashSet printJobManagers = new HashSet();
/**
* The constructor
*/
public PrintExamplePlugin()
{
plugin = this;
System.out.println("PrintExamplePlugin: ctor");
}
/*
* (non-Javadoc)
*
* @see org.eclipse.ui.plugin.AbstractRcpApplicationPlugin#
* start(org.osgi.framework.BundleContext)
*/
public void start(BundleContext context) throws Exception
{
super.start(context);
// Add the service manager listener
serviceManager = RcpRuntimePlugin.getDefault().getServiceManager();
serviceManager.addServiceManagerListener(this);
}
/*
* (non-Javadoc)
*
* @see org.eclipse.ui.plugin.AbstractRcpApplicationPlugin#stop(org.osgi.
* framework.BundleContext)
*/
public void stop(BundleContext context) throws Exception
{
plugin = null;
// Remove the service manager listener
if (serviceManager != null)
serviceManager.removeServiceManagerListener(this);
super.stop(context);
}
/**
* Returns the shared instance
*
* @return the shared instance
*/
public static PrintExamplePlugin getDefault()
{
return plugin;
}
/**
* Returns an image descriptor for the image file at the given plug-in
* relative path
*
* @param path
* the path
* @return the image descriptor
*/
public static ImageDescriptor getImageDescriptor(String path)
{
return imageDescriptorFromPlugin(PLUGIN_ID, path);
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.IPrintJobManagerChangeListener#
* addPrintJob(com.ibm.hats.runtime.PrintJobManager,
* com.ibm.hats.runtime.PrintJob)
*/
public void addPrintJob(PrintJobManager printJobManager,
PrintJob printJob)
{
System.out.println("PrintExamplePlugin: addPrintJob:
" + printJob.toString());
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.IPrintJobManagerChangeListener#
* removePrintJob(com.ibm.hats.runtime.PrintJobManager,
* com.ibm.hats.runtime.PrintJob)
*/
public void removePrintJob(PrintJobManager printJobManager,
PrintJob printJob)
{
System.out.println("PrintExamplePlugin: removePrintJob: "
+ printJob.toString());
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.IPrintJobManagerChangeListener#
* updatePrintJob(com.ibm.hats.runtime.PrintJobManager,
* com.ibm.hats.runtime.PrintJob)
*/
public void updatePrintJob(PrintJobManager printJobManager,
PrintJob printJob)
{
System.out.println("PrintExamplePlugin: updatePrintJob: "
+ printJob.toString());
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.events.ServiceManagerListener#
* serviceChanged(com.ibm.hats.runtime.events.ServiceManagerEvent)
*/
public void serviceChanged(ServiceManagerEvent event)
{
IService theService = event.getService();
if (theService instanceof ISessionService)
{
ISessionService sessionService = (ISessionService) theService;
int type = event.getType();
if (type == ServiceManagerEvent.TYPE_SERVICE_CREATED)
{
sessionService.addSessionServiceListener(this);
}
else if (type == ServiceManagerEvent.TYPE_SERVICE_DESTROYED)
{
sessionService.removeSessionServiceListener(this);
}
}
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.events.SessionStateListener#
* sessionStateChanged(com.ibm.hats.runtime.events.SessionStateEvent)
*/
public void sessionStateChanged(StateChangeEvent event)
{
// If the session has change to operational then add a listener to
// the PrintJobManager (if there is one and we haven't already done so).
StateType state = event.getNewState();
if (state == StateType.OPERATIONAL)
{
ISessionService sessionService = event.getSessionService();
ClientSpecificInfo csi = sessionService.getRuntimeService()
.getClientContainer().accessClient(sessionService.getClientId());
if (csi != null)
{
String asiId = ApplicationSpecificInfo.
createCompositeAsiId(sessionService.
getApplicationId(),
sessionService.getViewId());
ApplicationSpecificInfo asi = csi.peekAll(asiId);
if (asi != null)
{
PrintSpecificInfo psi = asi.getPrint();
if (psi != null)
{
PrintResourceHandler prh = psi.getResourceHandler();
if (prh != null)
{
PrintJobManager pjm = prh.getPrintJobManager();
// Add this PrintJobManager to our list of
// PrintJobManagers.
// This will return true if we haven't encountered
// this PrintJobManager before.
// In this case, add ourselves as a
// listener to this PrintJobManager.
if (printJobManagers.add(pjm))
{
pjm.addChangeListener(this);
}
}
}
}
}
}
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.events.ISessionServiceListener#
* aboutToProcessCommand(com.ibm.hats.runtime.events.CommandEvent)
*/
public void aboutToProcessCommand(CommandEvent event)
{
}
/*
* (non-Javadoc)
*
* @see com.ibm.hats.runtime.events.ISessionServiceListener#
* afterProcessCommand(com.ibm.hats.runtime.events.CommandEvent)
*/
public void afterProcessCommand(CommandEvent event)
{
}
}
SWT Composites referenced in a Show Composite Action should implement the com.ibm.hats.rcp.transform.IRenderable interface. If the SWT Composite implements com.ibm.hats.rcp.transform.IRenderable, it will have access to the RcpContextAttributes that contains, among other things, the ISessionService for the session the composite is being shown in. A sendContinue() method on the ISessionService can be called to resume executing the HATS application.
To create a composite using the Visual Editor (see Editing transformations):
To add a continue button to the composite using the Visual Editor (see Editing transformations):
RcpContextAttributes contextAttributes =
(RcpContextAttributes)getContextAttributes();
ISessionService sessionService = contextAttributes.getSessionService();
sessionService.sendContinue();