uCosminexus Service Platform, Basic Development Guide

[Contents][Glossary][Index][Back][Next]

8.2.10 Creating a service requester that sends a request for the operating status of service adapter from an application (Web Services and SOAP communication infrastructure)

You can create a service requester that sends a request for the service adapter's operating status from an application to the standard synchronous reception (Web Services).

To check the operating status of a service adapter, apart from invoking the service component that sends a request to the standard synchronous reception (Web Services), you must add a process for invoking the method for checking the operating status.

The following figure shows a procedure for creating a service requester that sends a request for checking the operating status of the service adapter from an application to the standard synchronous reception (Web Services):

Figure 8-11 Procedure for creating a service requester that sends a request for checking the operating status of the service adapter (Standard synchronous reception (Web Services and SOAP communication infrastructure))

[Figure]

The tasks in the individual steps are described below.

Organization of this subsection
(1) WSDL acquisition
(2) Stub creation
(3) Object generation
(4) Parameter specification
(5) Response message acquisition
(6) Error information acquisition

(1) WSDL acquisition

The WSDL acquisition method is the same as that used for creating an ordinary service requester that sends requests to the standard synchronous reception (Web Services).

Note that you need not use different WSDLs in the process for invoking the service component and in the process for checking the operating status.

For details about the WSDL acquisition method, 8.2.2 Acquiring the WSDL.

(2) Stub creation

The stub creation method is the same as the one used for creating an ordinary service requester that sends requests to the standard synchronous reception (Web Services). That is, to create a stub, you use the WSDL2Java command provided by Cosminexus as a development support command.

For details about stub creation, see 8.2.3 Creating Stubs.

(3) Object generation

To generate an object for invoking a method of requesting for the service adapter's operating status (Web Services):

  1. Create a CSCMsgSyncServiceDeliveryWSImplServiceLocator class object, which is the service component's interface class.
    Example:
     
    CSCMsgSyncServiceDeliveryWSImplServiceLocator locator
                 = new CSCMsgSyncServiceDeliveryWSImplServiceLocator();
     
  2. Using the service component's interface class object, create a CSCMsgSyncServiceDeliveryWSImpl.java class object, which is the service requester's interface class.
    The instance of the service requester's interface class created or acquired cannot be shared by multiple threads.
    Example:
     
    CSCMsgSyncServiceDeliveryWSImpl ws = null;
    try {
          ws = locator.getCSCMsgSyncServiceDeliveryWSImpl();
    }catch (ServiceException e) {
                  e.printStackTrace();
                  return;
    }
     
     
    The connection destination to the service component is the location attribute, which is an address child element of the Service element inside the WSDL definition. To acquire the connection destination to the service component within the service requester's program, use the following coding:
    Example:
     
    String url = locator.getCSCMsgSyncServiceDeliveryWSImplAddress();
     
  3. Using the created CSCMsgSyncServiceDeliveryWSImpl.java class object, invoke a method of requesting for the operating status of the service adapter of the standard synchronous reception (Web Services).
    Example: When "type=status" is specified in the option
     
    String result = ws.getServiceInfo(          // Method invocation
                           serviceName,         // Service name
                           clientID,            // Client correlation ID
                           "type=status");      // Option
     
    Example: When "type=status,returnType=XML" is specified in the option
     
    String result = ws.getServiceInfo(          // Method invocation
                           serviceName,         // Service name
                           clientID,            // Client correlation ID
                           "type=status,returnType=XML");
                                                // Option
     

(4) Parameter specification

Use the getServiceInfo method to request checking of the operating status of service adapters. The parameters that become the arguments of the method are different from those used in creating an ordinary service requester that sends requests to the standard synchronous reception (Web Services).

The following table shows the details of the parameters that are specified for a service requester that sends a request to a synchronous reception (Web Services) for the service adapter's operating status.

Table 8-7 Parameter details (Standard synchronous reception (Web Services) or service adapter operating status checking request)

Parameter name Data type Parameter (invokeBPXML) Explanation
Service name
(serviceName)
java.lang.String in0(type="xsd:string") This is the service name of the request destination when the operating status of service adapter is checked.
This parameter is required.
For the service name of the request destination, specify the service adapter deployed on the HCSC server.
Client correlation ID
(clientID)
java.lang.String in1(type="xsd:string") This is a correlation identifier for uniquely identifying the request message from the service requester.
Specify alphanumeric characters, underscore (_), period (.), and hyphen (-) up to 255 characters.
This parameter is used to map the request message from the service requester to the execution history, logs, and traces managed by the HCSC server. Therefore, specify a different ID for each request message sent to the HCSC server.
To omit the client correlation ID, specify NULL.
Option
(option)
java.lang.String in2(type="xsd:string") This is an option that is selected when acquiring the checked results of the operating status.
The input format of an option is Key name=Value. Enclose the option within double quotation marks ("). When specifying multiple options, demarcate with a comma (,).#1

Example
"key-name=value, key-name=value"

The following options can be specified:

type={all/status}
This is an option that specifies the pattern of the information to be acquired.
  • all
    The entire information, corresponding to the service name specified in serviceName, is sent as a response.
  • status
    The status, HCSC server name, and the cluster name corresponding to the service name specified in serviceName is sent as a response.

returnType={Properties/String/XML}
This is an option that specifies the response format.
  • Properties
    All properties included in the java.util.Properties class are sent as a response in the XML document format#2. If there is no value, the property key does not exist.#3
  • String
    The java.util.Properties class is sent as a response in the toString() converted format. If there is no value, the property key does not exist.
  • XML
    The XML schema defined in the HCSC server is sent as a response in the XML document format. If there is no value, an empty tag is sent as a response.

Legend:
inX (X=1 to 2): Parameter for each method indicated by a stub

#1
If a space exists before or after a comma (,), or before or after an equal sign (=), this will result in an error. Also, make sure that a character string does not end with a comma (,).

#2
This is a UTF-8 encoded XML format that uses the storeToXML() method of the Properties class. This format can be restored to the Properties class using the loadFromXML() method of the Properties class.

#3
When the value is acquired with the Properties class, null will be sent as a response.

(5) Response message acquisition

The response message of the operating status check of service adapters is returned in the format specified in the parameter option.

The format and examples of response messages are described in the following points:

(a) Format of a response message

The information that can be acquired with a response message depends on the contents specified in the type option. The following information can be acquired with a response message:

Table 8-8 Information that can be acquired with a response message

Key or tag Information contents Response information based on the type option specification
all status
HCSCServerName HCSC server name Y Y
ClusterName Cluster name Y Y
ServiceName Service name Y --
ServiceStatus Service adapter status Y Y
ServiceKind Service type Y --
ServiceProtocolKind Adapter protocol type Y --
AdapterName Adapter name Y --
AdapterLocalCall Local key usage status Y# --
EntryTime Adapter definition addition time Y --
ModifiedTime Adapter definition update time Y --

Legend:
Y: Can be acquired.
--: Cannot be acquired.

#
A response is sent only when ServiceProtocolKind is MDB_WSR.

The details of the acquired information are as follows:

[Figure]HCSCServerName
Explanation
Acquires the HCSC server name in which the information is acquired.

[Figure]ClusterName
Explanation
Acquires the cluster name to which the adapter (service adapter) belongs.

[Figure]ServiceName
Explanation
Acquires the deployed service name when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.

[Figure]ServiceStatus
Explanation
Acquires the status of the service adapter.
  • active: Running
  • inactive: Stopped
  • starting: Starting
  • startfailed: Failed to start
  • stopping: Stopping
  • stopfailed: Failed to stop
  • deleting: Deleting

[Figure]ServiceKind
Explanation
Acquires the type of the deployed service when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.
  • ServiceAdapter: Service adapter

[Figure]ServiceProtocolKind
Explanation
Acquires the type of the adapter protocol when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.
  • WebService: SOAP (HTTP) (Synchronous reception (Web Services))
  • SessionBean: RMI-IIOP (Synchronous reception (SessionBean))
  • MDB_WSR: WS-R (Asynchronous reception (MDB (WS-R)))
  • MDB_DBQ: Protocol or JMS unique to Cosminexus RM (Asynchronous reception (MDB (database queue)))
  • Custom: Custom adapter

[Figure]AdapterName
Explanation
Acquires the deployed adapter name when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.

[Figure]AdapterLocalCall
Explanation
Acquires the usage status of a local key of the adapter when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.
This item is sent as a response only when ServiceProtocolKind is MDB_WSR.
  • true: A local key is used
  • false: A local key is not used

[Figure]EntryTime
Explanation
Sends (as a response) the time (time registered in the definition) at which the service adapter was deployed, when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.
Format
 
YYYY/MM/DD hh:mm:ss.SSS
 
  • YYYY: Year
  • MM: Month
  • DD: Date
  • hh: Hour
  • mm: Minutes
  • ss: Seconds
  • SSS: Milli seconds

[Figure]ModifiedTime
Explanation
Sends (as a response) the time (time registered in the definition) at which the service adapter was defined in the development environment, when "type=all" is specified in the option. If "type=status" is specified in the option, this information will not be acquired.
Format
 
YYYY/MM/DD hh:mm:ss
 
  • YYYY: Year
  • MM: Month
  • DD: Date
  • hh: Hour
  • mm: Minutes
  • ss: Seconds
(b) Examples of response messages

Examples of response messages are described below.

Example 1: When "type=all,returnType=Properties" is specified in the option:
<?xml version="1.0" encoding="UTF-8"?>
<getServiceInfoResponse>
<HCSCServerName>HCSC</HCSCServerName>
<ClusterName>Cluster</ClusterName>
<ServiceName>Service1</ServiceName>
<ServiceStatus>Active</ServiceStatus>
<ServiceKind>ServiceAdapter</ServiceKind>
<ServiceProtocolKind>WebService</ServiceProtocolKind>
<AdapterName>ad1</AdapterName><AdapterLocalCall/>
<EntryTime>YYYY/MM/DD hh:mm:ss.SSS</EntryTime>
<ModifiedTime>YYYY/MM/DD hh:mm:ss</ModifiedTime>
</getServiceInfoResponse>

#1
The order of the values might vary (can be in any order).

#2
When "type=status,returnType=Properties" is specified in the option, the information that is not to be sent as a response does not exist in the response message.

Example 2: When "type=all,returnType=String" is specified in the option:
{HCSCServerName=HCSC,ClusterName=Cluster,ServiceName=Service1,ServiceStatus=Active,ServiceKind=ServiceAdapter,ServiceProtocolKind=WebService,AdapterName=ad1,EntryTime=YYYY/MM/DD hh:mm:ss.SSS,ModifiedTime=YYYY/MM/DD hh:mm:ss}

#1
The order of the values may vary (can be in any order).

#2
When "type=status,returnType=String" is specified in the option, the information that is not to be sent as a response does not exist in the response message.

Example 3 When "type=all,returnType=XML" is specified in the option:
<?xml version="1.0" encoding="UTF-8"?>
<getServiceInfoResponse>
<HCSCServerName>HCSC</HCSCServerName>
<ClusterName>Cluster</ClusterName>
<ServiceName>Service1</ServiceName>
<ServiceStatus>Active</ServiceStatus>
<ServiceKind>ServiceAdapter</ServiceKind>
<ServiceProtocolKind>WebService</ServiceProtocolKind>
<AdapterName>ad1</AdapterName>
<AdapterLocalCall/>
<EntryTime>YYYY/MM/DD hh:mm:ss.SSS</EntryTime>
<ModifiedTime>YYYY/MM/DD hh:mm:ss</ModifiedTime>
</getServiceInfoResponse>

#1
When no value exists, an empty tag is sent as a response.
Example
<AdapterLocalCall/>

#2
When "type=status,returnType=XML" is specified in the option, <tag> of the information that is not to be sent as a response does not exist in the response message.

(6) Error information acquisition

When an error occurs while checking the operating status of the service adapter, catch the CSCMsgServerFaultException object and acquire the error information of SOAPFault.

For details about error information acquisition, see 8.2.8 Acquiring Error Information.

The main causes of occurrence of an error are as follows: