All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class COM.meitca.concordia.service.ServiceBridge 


java.lang.Object

   |

   +----java.rmi.server.RemoteObject

           |

           +----java.rmi.server.RemoteServer

                   |

                   +----java.rmi.server.UnicastRemoteObject

                           |

                           +----COM.meitca.concordia.service.ServiceBase

                                   |

                                   +----COM.meitca.concordia.service.ServiceBridge
public abstract class ServiceBridge
extends ServiceBase
An abstract base class for service bridges. A service bridge is a gateway between a Concordia system and another type of server (e.g., a database server). Application-specific bridges are generated by subclassing ServiceBridge and adding functionality where needed.

Note:Classed derived from ServiceBridge must supply at least one constructor in order to work properly with the Concordia server: either a default constructor (a constructor with no arguments), or a constructor with one String argument (the ServiceBridge's name). These constructors could be like the following: 

 public class MyService extends ServiceBridge {
     public MyService() throws RemoteException {
         super("MyServiceName");
     }
     public MyService(String theName) throws RemoteException
         super(theName);
     }

Constructor Index

o ServiceBridge(String)
Creates a ServiceBridge object with the specified name.
o ServiceBridge(String, Properties)
Creates a ServiceBridge object with the specified name and default properties.
o ServiceBridge(String, String, Properties)
Creates a ServiceBridge object with the specified name, default properties, and debug-facility name.

Method Index

o debug(String, int, String)
Logs a debug message to the Concordia log file on behalf of the ServiceBridge.
o getName()
Returns the name of this ServiceBridge.
o getProperties()
Returns a java.util.Properties object containing all of the properties set for the service bridge.
o getProperty(String)
Returns the value of a property.
o getProperty(String, String)
Returns the value of a property.
o getServiceBridge(String)
Returns a reference to a specified ServiceBridge.
o getServiceStatistics()
Requests an table containing current execution statistics for the ServiceBridge.
o getServiceStatisticsInfo()
Requests an array of objects containing descriptive text for each of the performance objects that could be returned by getServerStatistics().
o killService()
Stops the ServiceBridge with prejudice.
o resetServiceStatistics()
Resets any statistics counters being maintained by the ServiceBridge back to their initial state (usually zero).
o resumeService()
ServiceBridge specific extensions to be performed while resuming the ServiceBridge.
o setProperties(Properties)
The setProperties allows the ServiceBridge to replace it existing properties with an entirely new set of values.
o setProperty(String, String)
Sets the specified property to the new value.
o startService()
The startService method is invoked by the Concordia Server to handle any ServiceBridge-specific startup and begin service processing.
o stopService(Date)
ServiceBridge specific extensions to be performed before stopping the ServiceBridge.
o suspendService()
Suspends the main thread of the ServiceBridge.
o syncServiceProperties()
Notifies the ServiceBridge that some of it operating properties have been changed by a remote administrator.

Constructors

o ServiceBridge 

 protected ServiceBridge(String serviceBridgeName) throws RemoteException
Creates a ServiceBridge object with the specified name. This constructor will be called by the ConcordiaServer at startup. The name passed as the parameter of this method, is the name assigned to this ServiceBridge using the Concordia Administrator. If derived classes do not supply this method, the default constructor will be called.

Derived classes should do extra initialization activity in the startService method.

Parameters:
serviceBridgeName - This ServiceBridge's name. This name will be used by the Concordia Administrator and by Agents to identify the Service Bridge.
o ServiceBridge 

 public ServiceBridge(String serviceBridgeName,

                      Properties defaults) throws RemoteException
Creates a ServiceBridge object with the specified name and default properties.

This constructor is not directly called by the Concordia Server. It is meant to be called by other constructors, as in the following: 

 public class MyService extends ServiceBridge {
     private static Properties   DEFAULTS;
     static {
         DEFAULTS = new Properties();
         DEFAULTS.put("TestProperty", "true");
         DEFAULTS.put("SecondTestProperty", "12");
         DEFAULTS.put("ThirdTestProperty", "Agents"); 15:
     }
     public MyService() throws RemoteException {
         super("MyServiceName", DEFAULTS);
     }
     public MyService(String theName) throws RemoteException {
         super(theName, DEFAULTS);
     }

Derived classes should do their initialization activity in the startService method.

Parameters:
serviceBridgeName - This ServiceBridge's name. This name will be used by the Concordia Administrator and by Agents to identify the Service Bridge.
defaults - Default properties for this ServiceBridge. The author of a ServiceBridge can use properties to support remote administration via the Concordia Administrator. For more information see the Accessing Native Services section of the Concordia Developers Guide.
o ServiceBridge 

 public ServiceBridge(String serviceBridgeName,

                      String facility,

                      Properties defaults) throws RemoteException
Creates a ServiceBridge object with the specified name, default properties, and debug-facility name.

This constructor is not directly called by the Concordia Server. It is meant to be called by other constructors, as in the following: 

 public class MyService extends ServiceBridge {
     private static Properties   DEFAULTS;
     static {
         DEFAULTS = new Properties();
         DEFAULTS.put("TestProperty", "true");
         DEFAULTS.put("SecondTestProperty", "12");
         DEFAULTS.put("ThirdTestProperty", "Agents"); 15:
     }
     public MyService() throws RemoteException {
         super("MyServiceName", "MyFacilityName", DEFAULTS);
     }
     public MyService(String theName) throws RemoteException {
         super(theName, "MyFacilityName", DEFAULTS);
     }

Derived classes should do their initialization activity in the startService method.

Parameters:
serviceBridgeName - This ServiceBridge's name. This name will be used by the Concordia Administrator and by Agents to identify the Service Bridge.
facility - A Debug facility name. The debug facility writes debug information about the ServiceBridge into the Concordia debug log file. Normally, agent developers do not need to specify this name. If this parameter is specified as null or "", the serverName will be used as the facility name.
defaults - Default properties for this ServiceBridge. The author of a ServiceBridge can use properties to support remote administration via the Concordia Administrator. For more information see the Accessing Native Services section of the Concordia Developers Guide.

Methods

o getServiceBridge 

 public static ServiceBridge getServiceBridge(String bridgeName) throws NoSuchServiceException
Returns a reference to a specified ServiceBridge. This method can be used by agents to locate service bridges running within a given Concordia server as in the following example; 

 public class QueryAgent extends Agent {
     public void queryDatabase() {
         try {
             // retrieve a (local) reference to the Sales Database
             SalesDatabase db = (SalesDatabase)ServiceBridge.getServiceBridge("SalesDatabase");
         } catch (NoSuchServiceException e) {
             System.err.println("SalesDatabase service not running.");
         }

Parameters:
bridgeName - The name of the ServiceBridge.
Returns:
A reference to the ServiceBridge identified by bridgeName.
Throws: NoSuchServiceException
If no ServiceBridge can be found with the given name.
o startService 

 protected void startService() throws ServiceException
The startService method is invoked by the Concordia Server to handle any ServiceBridge-specific startup and begin service processing. Derived classes should override startService to perform any initialization tasks.

Throws: ServiceException
The ServiceBridge should throw this exception if any errors occurr starting the server.
Overrides:
startService in class ServiceBase
o stopService 

 protected void stopService(Date timeout) throws ServiceException, ServiceTimeoutException, ServiceWrongStateException
ServiceBridge specific extensions to be performed before stopping the ServiceBridge. Derived classes should override stopService to perform any shutdown tasks.
The ServiceBridge should attempt to perform a clean shutdown. Dependent threads should be notified of the shutdown and important pending tasks should be allowed to complete.

Parameters:
timeout - The maximum amount of time to wait for a a clean shutdown If the timeout parameter is null, the timeout is disabled and the method can wait indefinitely. If the shutdown operation times out, then this method should throw an ServiceTimeoutException
Throws: ServiceException
If an error occurs while stopping the server.
Throws: ServiceTimeoutException
If the server can not stop within the specified time limit.
Throws: ServiceWrongStateException
If the server is a state that will not allow a clean shutdown (for example if the server is already shutdown).
Overrides:
stopService in class ServiceBase
o killService 

 protected void killService() throws ServiceException, ServiceWrongStateException
Stops the ServiceBridge with prejudice. Any pending tasks will be aborted, and all threads will be killed. Derived classes should override killService to perform shutdown tasks related to the killing of the server.

Throws: ServiceException
If an error occurrs killing the server.
Throws: ServiceWrongStateException
If the service is in a state that will not allow it to be killed (for example if the service is already shutdown).
Overrides:
killService in class ServiceBase
o suspendService 

 protected void suspendService() throws ServiceException, ServiceWrongStateException
Suspends the main thread of the ServiceBridge. It is undefined whether subthreads of the server are also suspended. In general, when suspended, a ServiceBridge will refuse any requests nmade by agents. This behavior is, however, application specific. Derived classes should override this method to perform any tasks necessary to enter a suspended state.

Throws: ServiceException
If an error occurs suspending the server.
Throws: ServiceWrongStateException
If the server is a state that will not allow it to be suspended (for example if the server is shutdown).
Overrides:
suspendService in class ServiceBase
o resumeService 

 protected void resumeService() throws ServiceException, ServiceWrongStateException
ServiceBridge specific extensions to be performed while resuming the ServiceBridge. Resumes the main thread of the specified ServiceBridge that was suspended by suspendService. If subthreads of the main thread were suspended by suspendServer, those threads must also be resumed.

Derived classes should override this method to perform any tasks necessary to leave the suspended state.

Throws: ServiceException
If an error occurred resuming the ServiceBridge.
Throws: ServiceWrongStateException
If the ServiceBridge is in the wrong state (for example not suspended).
Overrides:
resumeService in class ServiceBase
o getServiceStatisticsInfo 

 protected PerformanceInfo[] getServiceStatisticsInfo()
Requests an array of objects containing descriptive text for each of the performance objects that could be returned by getServerStatistics().

Derived classes can override this method to provide any performance information to be presented to remote administrators.

Overrides:
getServiceStatisticsInfo in class ServiceBase
o getServiceStatistics 

 protected PerformanceData[] getServiceStatistics()
Requests an table containing current execution statistics for the ServiceBridge. If the ServiceBridge is not running, null is returned. These statistics can represent performance of the server.

Derived classes can override this method to provide any performance information to be presented to remote administrators.

Overrides:
getServiceStatistics in class ServiceBase
o resetServiceStatistics 

 protected void resetServiceStatistics()
Resets any statistics counters being maintained by the ServiceBridge back to their initial state (usually zero). Note that this method does not affect any other performance information which is not of a counter type (e.g., Strings, values, etc.) So for example, if the server is keeping a count of the number of agent requests it has satisfied, this method would reset that counter to 0.

Overrides:
resetServiceStatistics in class ServiceBase
o syncServiceProperties 

 protected void syncServiceProperties() throws ServicePropertySyncException
Notifies the ServiceBridge that some of it operating properties have been changed by a remote administrator. The ServiceBridge should now attempt to change its behavior to math the new properties. For example, if the ServiceBridge was performing some form of logging, and a remote administrator has modified a property that disabled logging, the ServiceBridge should at this point modify its behavior to disable that logging. This process of modifying the ServiceBridges behavior is known as syncing. If some properties of a ServiceBridge cannot be synced, this method should be return those names in the form of a ServicePropertySyncException

Throws: ServicePropertySyncException
if some of the properties could not by sync'd
Overrides:
syncServiceProperties in class ServiceBase
o getName 

 protected String getName()
Returns the name of this ServiceBridge. This name can be used by agents to locate a ServiceBridge running within a given Concordia server, using the getServiceBridge method.

Returns:
the name of this ServiceBridge (a string)
Overrides:
getName in class ServiceBase
See Also:
getServiceBridge
o getProperty 

 protected String getProperty(String key,

                              String def)
Returns the value of a property. Properties can be used to store preferences or configuration options for the ServiceBridge. These properties can be remotely modified using the Concordia Administrator. ServiceBridges use the getProperty to retrieve the current values of properties. For example; 

 String debugProperty = getProperty("debugOn", "false");
 boolean debug = Boolean.valueOf(debugProperty).booleanValue();
 if (debug) {
     // perform debug specific work
 }

Parameters:
key - The name of the property to retrieve.
def - A default value for the property, if none is set.
Returns:
the propery value (a string)
Overrides:
getProperty in class ServiceBase
o getProperty 

 protected String getProperty(String key)
Returns the value of a property. Properties can be used to store preferences or configuration options for the ServiceBridge. These properties can be remotely modified using the Concordia Administrator. ServiceBridges use the getProperty to retrieve the current values of properties. For example; 

 String debugProperty = getProperty("debugOn");
 boolean debug = Boolean.valueOf(debugProperty).booleanValue();
 if (debug) {
     // perform debug specific work
 }

Parameters:
key - The name of the property to retrieve.
Returns:
the propery value (a string)
Overrides:
getProperty in class ServiceBase
o getProperties 

 protected Properties getProperties()
Returns a java.util.Properties object containing all of the properties set for the service bridge.

Returns:
A java.util.Properties object containing all of the properties set for the service bridge.
Overrides:
getProperties in class ServiceBase
o setProperty 

 protected void setProperty(String prop_name,

                            String new_value)
Sets the specified property to the new value. Properties can be used to store preferences or configuration options for the ServiceBridge. These properties can be remotely modified using the Concordia Administrator. ServiceBridges use the setProperty to modify the values of a property. For example; 

 setProperty("debugOn", "true");

Normally, ServiceBridges will

Parameters:
prop_name - Name of the property to modify or set
new_value - New value of the property.
Overrides:
setProperty in class ServiceBase
o setProperties 

 protected void setProperties(Properties new_props)
The setProperties allows the ServiceBridge to replace it existing properties with an entirely new set of values. The caller passes in the new values in the form of a java.util.Properties object.

Parameters:
new_props - A java.util.Properties object containing new values for the ServiceBridge's properties.
Overrides:
setProperties in class ServiceBase
o debug 

 public void debug(String facility,

                   int level,

                   String message)
Logs a debug message to the Concordia log file on behalf of the ServiceBridge. Concordia logging can be used for debugging purposes or for error logging. Here's an example: 

 import COM.meitca.concordia.service.*;
 public class MyService extends ServiceBridge {
     public void doit() {
         // A simple debug message
         debug("MyServiceBridge", 1, "Agent arrived at service");
         // More verbose information
         debug("MyServiceBridge", 3, "AgentID is " + getAgentID());
     }
 }

Parameters:
facility - The facilty is a string which can be used to classify this debug message. Concordia logging supports enabling or disabling debugging on a per facility bases. Using facilities, a developer or administrator can filter out unwanted or unrelated information and focus in on particular areas of interest. Service Bridge developers can specify application specific facility names to aid in their debugging.
level - The debugging level specifies the level of detail at which this message should be logged. In general, when configuring Concordia server logging, an Administrator specifies the detail level for logging. This level is a numeric value. A value of 0 specifies very high level information. The larger the number specified the finer the level of detail and the more verbose the debug output. Service Bridge developers should generally specify low numeric values of high level debug output and high numeric values for verbose output.
message - The debug message to log. 

All Packages  Class Hierarchy  This Package  Previous  Next  Index