The following figure shows the order in which a reception process invokes the custom reception framework APIs.

Figure A-3 Invocation order of custom reception framework APIs

1. Invoke the newInstance method of the CSCMsgCustomServiceDeliveryFactory class and acquire the CSCMsgCustomServiceDeliveryFactory object.
2. Invoke the createCSCMsgCustomServiceDelivery method of the CSCMsgCustomServiceDeliveryFactory object acquired in step 1, and then acquire the CSCMsgCustomServiceDelivery object.
3. Invoke the invokeXML method or invokeBinary method of the CSCMsgCustomServiceDelivery object acquired in step 2, and then pass the request message to the custom reception framework.

(a) Description

The CSCMsgCustomServiceDeliveryFactory class is a factory class, whose functionality includes generating CSCMsgCustomServiceDeliveryFactory objects and CSCMsgCustomServiceDelivery objects.

(b) Format

 
package jp.co.Hitachi.soft.csc.msg.message.reception.custom;
public abstract class CSCMsgCustomServiceDeliveryFactory {
  public static CSCMsgCustomServiceDeliveryFactory newInstance();
  public CSCMsgCustomServiceDelivery createCSCMsgCustomServiceDelivery();
}
 

(c) Methods

The following table lists the methods associated with the CSCMsgCustomServiceDeliveryFactory class:

Method name	Function
newInstance method	Generates a CSCMsgCustomServiceDeliveryFactory object.
createCSCMsgCustomServiceDelivery method	Generates a CSCMsgCustomServiceDelivery object.

newInstance method

Description

This method generates a CSCMsgCustomServiceDeliveryFactory object.

Format

 
public static CSCMsgCustomServiceDeliveryFactory newInstance();
 

Parameters

None.

Exceptions

None.

Return values

• CSCMsgCustomServiceDeliveryFactory
  Returns a CSCMsgCustomServiceDeliveryFactory object.
  

createCSCMsgCustomServiceDelivery method

Description

This method generates a CSCMsgCustomServiceDelivery object.

Format

 
public CSCMsgCustomServiceDelivery createCSCMsgCustomServiceDelivery();
 

Parameters

None.

Exceptions

None.

Return values

• CSCMsgCustomServiceDelivery
  Returns a CSCMsgCustomServiceDelivery object.
  

(a) Description

This interface provides the methods used by the reception process of a custom reception to pass messages to and from the custom reception framework. It also provides a method for acquiring custom reception user files registered in the development environment.

(b) Format

 
package jp.co.Hitachi.soft.csc.msg.message.reception.custom;
public interface CSCMsgCustomServiceDelivery {
  public String invokeXML(String cscCorrelationID,
      String cscServiceOperationName, String msg)
      throws CSCMsgServerException;
  public byte[] invokeXML(String cscCorrelationID,
      String cscServiceOperationName, byte[] msg)
      throws CSCMsgServerException;
  public String invokeXML(String cscCorrelationID, String msg)
      throws CSCMsgServerException;
  public byte[] invokeXML(String cscCorrelationID, byte[] msg)
      throws CSCMsgServerException;
 
  public byte[] invokeBinary(String cscCorrelationID,
      String cscServiceOperationName,
      int requestMessageLength, byte[] msg)
      throws CSCMsgServerException;
  public byte[] invokeBinary(String cscCorrelationID,
      int requestMessageLength, byte[] msg)
      throws CSCMsgServerException;
  public InputStream getUserFile(String fileName);
}
 

(c) Methods

The following table lists the methods provided by the CSCMsgCustomServiceDelivery interface:

Method name	Function
invokeXML method (format 1)	Sends XML messages to the service associated with the specified operation name, and returns the responses to those messages.
invokeXML method (format 2)	Sends byte-array XML messages to the service associated with the specified operation name, and returns the responses to those messages. Responses will also be in byte-array format.
invokeXML method (format 3)#1	Sends XML messages to the service associated with the default operation name, and returns the responses to those messages.
invokeXML method (format 4)#1	Sends byte-array XML messages to the service associated with the default operation name, and returns the responses to those messages. Responses will also be in byte-array format.
invokeBinary method (format 1)	Sends binary messages to the service associated with the specified operation name, and returns the responses to those messages.
invokeBinary method (format 2)#2	Sends binary messages to the service associated with the default operation name, and returns the responses to those messages.
getUserFile method	Returns the InputStream value of the custom reception user file registered in the development environment.

#1

Equivalent to the invokeXML method (format 1) with the operation name omitted.

#2

Equivalent to the invokeBinary method (format 1) with the operation name omitted.

invokeXML method (format 1)

Description

This method sends XML messages to the service associated with the specified operation name, and returns the responses to those messages.

Format

 
public String invokeXML(String cscCorrelationID,
    String cscServiceOperationName, String msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation ID that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• cscServiceOperationName (operation name)
  The operation name associated with the service that is the recipient of the request.
  This parameter specifies the operation name of the service component defined in the development environment.
  A CSCMsgServerException exception is thrown if the operation name does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: Characters defined in the NCName data type in the XML schema
  A CSCMsgServerException exception is thrown if you specify an operation name that is not defined in the User-Defined Reception Definition window.
  If you do not intend to specify an operation name (you want to use the default operation name), specify null or an empty string ("").
  
• msg (user message)
  The request message from the service requester (XML format).
  If there is no request message, specify null or an empty string ("").
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request.
  

Return values

• String
  - If the communication model is synchronous
  Returns the response message (XML format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

invokeXML method (format 2)

Description

This method sends byte-array XML messages to the service associated with the specified operation name, and returns the responses to those messages. Responses will also be in byte-array format.

When a custom reception handles user messages in byte array format, you can use this method to skip the process of transforming messages to string format.

Format

 
public byte[] invokeXML(String cscCorrelationID,
    String cscServiceOperationName, byte[] msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation identifier that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• cscServiceOperationName (operation name)
  The operation name associated with the service that is the recipient of the request.
  This parameter specifies the operation name of the service component defined in the development environment.
  A CSCMsgServerException exception is thrown if the operation name does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: Characters defined in the NCName data type in the XML Schema
  A CSCMsgServerException exception is thrown if you specify an operation name that is not defined in the User-Defined Reception Definition window.
  If you do not intend to specify an operation name (you want to use the default operation name), specify null or an empty string ("").
  
• msg (user message)
  The request message from the service requester (XML format).
  If there is no request message, specify null.
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request.
  

Return values

• byte[]
  - If the communication model is synchronous
  Returns the response message (XML format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

invokeXML method (format 3)

Description

This method sends XML messages to the service associated with the default operation name, and returns the responses to those messages.

Format

 
public String invokeXML(String cscCorrelationID, String msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation identifier that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• msg (user message)
  The request message from the service requester (XML format).
  If there is no request message, specify null or an empty string ("").
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request.
  

Return values

• String
  - If the communication model is synchronous
  Returns the response message (XML format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

invokeXML method (format 4)

Description

This method sends byte-array XML messages to the service associated with the default operation name, and returns the responses to those messages. Responses will also be in byte-array format.

When a custom reception handles user messages in byte array format, you can use this method to skip the process of transforming messages to string format.

Format

 
public byte[] invokeXML(String cscCorrelationID, byte[] msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation identifier that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• msg (user message)
  The request message from the service requester (XML format).
  If there is no request message, specify null.
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request.
  

Return values

• byte[]
  - If the communication model is synchronous
  Returns the response message (XML format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

invokeBinary method (format 1)

Description

This method sends binary messages to the service associated with the specified operation name, and returns the responses to those messages.

Format

 
public byte[] invokeBinary(String cscCorrelationID,
    String cscServiceOperationName, int requestMessageLength, byte[] msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation identifier that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• cscServiceOperationName (operation name)
  The operation name associated with the service that is the recipient of the request.
  This parameter specifies the operation name of the service component defined in the development environment.
  A CSCMsgServerException exception is thrown if the operation name does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: Characters defined in the NCName data type in the XML Schema
  A CSCMsgServerException exception is thrown if you specify an operation name that is not defined in the User-Defined Reception Definition screen.
  If you do not intend to specify an operation name (you want to use the default operation name), specify null or an empty string ("").
  
• requestMessageLength (user message length)
  The length of the request message.
  A CSCMsgServerException exception is thrown if the user message length does not comply with the following restrictions:
  - An integer value of 0 or greater
  - An integer value not exceeding the byte length of the user message (msg parameter)
  If there is no request message, specify 0.
  If you specify a smaller value than the byte length of the user message (msg parameter), the method uses the user message length (specified by the requestMessageLength parameter) as the length of the request message. In other words, the request message passed to the service component only includes the part of the user message (msg parameter) that spans the user message length (requestMessageLength parameter) + 1 byte.
  
• msg (user message)
  The request message from the service requester (binary format).
  If there is no request message, specify null or a 0-byte byte array.
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request.
  

Return values

• byte[]
  - If the communication model is synchronous
  Returns the response message (binary format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

invokeBinary method (format 2)

Description

This method sends binary messages to the service associated with the default operation name, and returns the responses to those messages.

Format

 
public byte[] invokeBinary(String cscCorrelationID,
    int requestMessageLength, byte[] msg)
    throws CSCMsgServerException;
 

Parameters

• cscCorrelationID (client correlation ID)
  The client correlation ID is a correlation identifier that uniquely identifies request messages from the service requester.
  A CSCMsgServerException exception is thrown if the client correlation ID does not comply with the following restrictions:
  - Size: 255 or fewer characters
  - Usable characters: One-byte alphanumeric characters, underscores (_), periods (.), and hyphens (-).
  The client correlation ID is used to establish mapping between the request messages from the service requester and the trace information and log data managed by the HCSC server. Therefore, you need to specify a different ID for each request message sent to the HCSC server.
  If you do not intend to specify a client correlation ID, specify null or an empty string ("").
  
• requestMessageLength (user message length)
  The length of the request message.
  A CSCMsgServerException exception is thrown if the user message length does not comply with the following restrictions:
  - An integer value of 0 or greater
  - An integer value not exceeding the byte length of the user message (msg parameter)
  If there is no request message, specify 0.
  If you specify a smaller value than the byte length of the user message (msg parameter), the method uses the user message length (specified by the requestMessageLength parameter) as the length of the request message. In other words, the request message passed to the service component only includes the part of the user message (msg parameter) that spans the user message length (requestMessageLength parameter) + 1 byte.
  
• msg (user message)
  The request message from the service requester (binary format).
  If there is no request message, specify null or a 0-byte byte array.
  

Exceptions

• CSCMsgServerException
  Thrown in the following circumstances:
  - An invalid value is specified in a method parameter.
  - An error occurred during data transformation of a request message or response message.
  - An error occurred in the service component targeted by the request
  

Return values

• byte[]
  - If the communication model is synchronous
  Returns the response message (binary format) corresponding to the execution request of the service component.
  If there is no response message, null is returned.
  - If the communication model is asynchronous
  null is returned.
  

getUserFile method

Description

This method reads the custom reception user file specified in the parameter, and returns the file contents as a stream.

The contents of the custom reception user file are returned as an unprocessed stream regardless of the file format. The appropriate processing for the file format must be applied at the invocation source. For example, you can use the load method of the Properties class to load the custom reception user file as a property file.

After using the stream acquired by this method, close the stream at the invocation source.

Format

 
public InputStream getUserFile(String fileName);
 

Parameters

• fileName
  The name of the custom reception user file.
  Specify the name of the custom reception user file you registered when defining the custom reception in the development environment.
  You can use any characters.
  

Exceptions

None.

Return values

• InputStream
  Returns the custom reception user file as a stream.
  If the method cannot locate the file specified in the fileName parameter, null is returned.
  

The following are examples in which the APIs of the custom reception framework are used to implement reception processes in EJB (Stateless Session Bean) format:

• MyReception.java
  

  package com.example.sample.reception.ejb; import javax.ejb.EJBObject; /** * Example of reception process (Stateless Session Bean) implementation (Remote interface) */ public interface MyReception extends EJBObject { public String invoke(String cscCorrelationID, String cscServiceOperationName, String msg) throws RemoteException; }

• MyReceptionHome.java
  

  package com.example.sample.reception.ejb; import java.rmi.RemoteException; import javax.ejb.CreateException; import javax.ejb.EJBHome; /** * Example of reception process (Stateless Session Bean) implementation (Home interface) */ public interface MyReceptionHome extends EJBHome { public MyReception create() throws RemoteException, CreateException; }

• MyReceptionBean.java
  

  package com.example.sample.reception.ejb; import java.rmi.RemoteException; import javax.ejb.CreateException; import javax.ejb.EJBException; import javax.ejb.SessionBean; import javax.ejb.SessionContext; import jp.co.Hitachi.soft.csc.msg.message.reception.CSCMsgServerException; import jp.co.Hitachi.soft.csc.msg.message.reception.custom.CSCMsgCustomServiceDelivery; import jp.co.Hitachi.soft.csc.msg.message.reception.custom.CSCMsgCustomServiceDeliveryFactory; /** * Example of reception process (Stateless Session Bean) implementation (Bean class) */ public class MyReceptionBean implements SessionBean { private static final CSCMsgCustomServiceDeliveryFactory factory = CSCMsgCustomServiceDeliveryFactory.newInstance(); private CSCMsgCustomServiceDelivery delivery; private SessionContext context; public MyReceptionBean() { } public void ejbActivate() throws EJBException, RemoteException { } public void ejbCreate() throws CreateException { // Generate CSCMsgCustomServiceDelivery object delivery = factory.createCSCMsgCustomServiceDelivery(); } public void ejbPassivate() throws EJBException, RemoteException { } public void ejbRemove() throws EJBException, RemoteException { // Discard CSCMsgCustomServiceDelivery object delivery = null; } public String invoke(final String cscCorrelationID, final String cscServiceOperationName, final String msg) { try { // Invoke custom reception framework final String response = delivery.invokeXML(cscCorrelationID, cscServiceOperationName, msg); return response; } catch (CSCMsgServerException e) { // Catch custom reception framework exceptions // Implement exception handling } } public void setSessionContext(final SessionContext sc) throws EJBException { context = sc; } }