One custom adapter can have multiple operations. For each operation, you need to design the operation name, communication model, request message, and response message.

(a) Determining the operation name

The operation name is an identifier used for distinguishing operations when a service requester calls a service component, or when the invoke service activity of a business process calls a service component.

Specify a name (255 bytes or less) that is unique within the custom adapter. Do not specify the same name as another operation in the same custom adapter.

You can specify the following characters and symbols:

• Alphanumeric characters
• Underscores (_)
• Periods (.)
• Hyphens (-)

The protocol converter in a custom adapter uses the operation name to identify which operation was called when the custom adapter was called.

(b) Determining the communication model

For a custom adapter, you can select the communication model for each operation. Select Sync or Async, depending on the service component to be called.

(c) Designing the request message and response message

Design the message forms and message formats for the request message received by the protocol converter and for the response message used by the response protocol converter. However, if the communication model is Async, no response message is returned, so you do not have to define the response message.

For the message format, you can select XML or binary format.

The message format depends on whether the XML-format data or binary-format data (other than XML-format data) is used for the message used for executing the service component. Select either XML or binary format depending on the service component to be called, and create a message format depending on the service component to be called.

For details about the difference between XML and binary format, see 4.2 Message Format Types in the manual Service Platform Basic Development Guide.

For details about how to create a message format when XML-format data is used, see 4.3 Creating Message Formats (XML Format Definition File) in the manual Service Platform Basic Development Guide. For details about how to create a message format when binary-format data (other than XML-format data) is used, see 4.4 Creating Message Formats (Binary Format Definition File) in the manual Service Platform Basic Development Guide.

Data transformation is required if the message format received by the protocol converter designed in 3.3.14(1) Designing operations is different from the message format of a request from the service requester or business process. You can set the message format in the Service Adapter Settings window.

To perform data transformation of a message, set the transformation-source message format definition file and transformation-destination message format definition file, and then define data transformation in the Data-conversion definition screen.

For details about data transformation, see Chapter 6. Defining Data Transformation in the manual Service Platform Basic Development Guide.

Create definition files that are used by the protocol converter and custom adapter development framework.

• Self-defined file for the protocol converter
• Custom adapter development framework action definition file
• Custom adapter property file
• HITACHI Application Integrated Property File for the custom adapter
• Custom adapter definition file

Set the created definition files in the Service Adapter Settings window in the development environment.

The following describes the contents of the files to be created.

(a) Self-defined file for the protocol converter

The protocol converter can read the contents of the resources set for a general custom adapter, via the adapter context.

Create this file if a file is necessary for operation of the protocol converter.

(b) Custom adapter development framework action definition file

Specify the class name (including the package name) of the protocol converter used by the custom adapter development framework. Specify framework_properties.xml for the file name.

For details about the settings in the custom adapter development framework action definition file, see B.2(1) Custom adapter development framework action definition file.

(c) Custom adapter property file

Create this file as necessary (for example, when you want to have the protocol converter settings in an external file). This is a kind of self-defined file, and is used when a custom adapter is defined. Specify customadapter_properties.xml for the file name.

For details about the settings in the custom adapter property file, see B.2(2) Custom adapter property file.

(d) HITACHI Application Integrated Property File for the custom adapter

You can use the HITACHI Application Integrated Property File for the custom adapter to set the parameters of the custom adapter according to your environment. Specify cscadapter_property.xml for the name of the HITACHI Application Integrated Property File for a custom adapter.

For details about the settings in the HITACHI Application Integrated Property File, see B.2(3) HITACHI Application Integrated Property File for custom adapter.

If you specify a HITACHI Application Integrated Property File, the value of <pooled-instance> of the Session Bean attribute will be the value specified in the HITACHI Application Integrated Property File.

(e) Custom adapter definition file

You can use the custom adapter definition file to use the function for skipping message structure transformation (structure transformation skip function) during data transformation. Specify csccustomadapter.properties for the name of the custom adapter definition file.

For details about the settings in the custom adapter definition file, see B.2(4) Custom adapter definition file.

The following describes how to set the structure transformation skip function:

In data transformation for a request message, you might want to create a request message in binary format directly from the DOM tree received from a business process, and then pass the request message to a custom adapter. If so, you can enable the structure transformation skip function.

In data transformation for a response message, you might want to pass a DOM tree generated from the response message (in binary format, returned from a custom adapter) to the business process as is. If so, you can enable the structure transformation skip function.

To set the structure transformation skip function, in the Service Adapter Settings (details) window in the development environment, set the custom adapter definition file for Self-defined file.

For details about the Service Adapter Settings window, see 1.2.2 Service Adapter Definition Window in the manual Service Platform, Reference Guide.

The following are notes on using the structure transformation skip function:

• In the Service Adapter Settings window in the development environment, specify the XML format definition file for the standard message format for a request message and response message. Also, specify the binary format definition file for the service message format of the request message and response message.
• In the Service Adapter Settings window in the development environment, specify the XML format definition file for the standard message format for the request message and response message. This XML format definition file must be generated by using the cscdfx2xsd command based on the reception message format (binary format definition file).

Create a class file that implements the protocol converter (protocol conversion processing). The class file to be created implements the CSCMsgCustomProtocolConverter interface provided by the custom adapter development framework.

The protocol converter operates as part of the Stateless Session Bean running on the service platform. Therefore, when you create a class file, see the descriptions regarding EJB and Stateless Session Bean in the Application Server EJB Container Functionality Guide.

For details about the CSCMsgCustomProtocolConverter interface, see B.1(1)(a) CSCMsgCustomProtocolConverter interface. For details about example implementations, see B.3 Sample program of the custom adapter development framework.

The following describes what should be considered when you implement the protocol converter.

(a) Relationship between custom adapter instances and the protocol converter instance

One custom adapter can have multiple instances. However, the protocol converter always has one instance. Therefore, when you implement the protocol converter, note that the protocol converter will be accessed by multiple threads.

Figure 3-30 Relationship between custom adapter instances and the protocol converter instance

(b) How to allocate resources

The custom adapter development framework recommends the following methods to allocate resources for the protocol converter:

• Acquiring static resources: start method of CSCMsgCustomProtocolConverter
  For resources only referenced when a service component is called, the framework recommends that you use the start method to allocate the resources to the instance field. Such resources include the header information of the protocol necessary for service component calls, or the address of the service component.
  The reason for the above is that if a resource is acquired once when a custom adapter starts, the same resource can continue to be used.
  
• Acquiring dynamic resources (non-thread-safe resources): invoke method of CSCMsgCustomProtocolConverter
  For resources for which tread-safe access is not available (such as streaming file access, and connection to a service component), the framework recommends that you acquire the resources each time the invoke method calls a service component.
  If you allocate resources for which thread-safe access is not available to the instance field, exclusive control among threads will be required.
  If you acquire resources each time a service component is called, you can suppress the deterioration of processing performance caused by exclusive control among threads.
  

  Note

  Resources that are allocated once are retained, even after processing finishes. Therefore, if a high load is applied to the whole system, an OutOfMemoryError might occur due to a shortage of Java heap or Perm heap. Therefore, you must implement a process for adequately releasing the resources in the event of an OutOfMemoryError, or error processing such as rollback.

(c) How to specify a resource file name

The protocol converter can access the resource files in the archive file by using the adapter context. When accessing a resource file in the archive file, note the following:

• Specify a file name that includes the relative path in the archive.
• If the name of a self-defined file is the same as a resource file in the archive file, the system assumes that you specified the self-defined file.
• Do not place resource files of the same name in multiple archive files. If there are files of the same name, the system cannot identify which file belongs to which archive.

(d) Difference between fault information and exceptions

If an error occurs while the invoke method of CSCMsgCustomProtocolConverter is being executed, the protocol converter generates and issues an exception, or stores fault information in the response message.

Fault information is used to report a fault in a business operation that occurs while service component call processing (invoke method of CSCMsgCustomProtocolConverter) is being executed, to the custom adapter development framework.

An exception is used to report a system error (such as a communication error that occurs during the service component call processing) to the custom adapter development framework.

In the service adapter and business process that receive error information, there are the following differences between when a fault is used and when an exception is used:

Fault information

• Response to the service requester
  For details about how to acquire fault information, see 8.2.8 Acquiring Error Information or 8.4.7 Acquiring Error Information in the manual Service Platform Basic Development Guide.
  
• Response to the business process
  A business process can process fault information in the same way as a fault of another service adapter provided by the service platform. For details about fault processing in a business process, see 5.4.3 Defining Fault Handling in the Service Platform Basic Development Guide.
  

Reference note

Fault information reported to the custom adapter development framework has elements that correspond to the SOAP Fault information of SOAP. The method of using each element is also conforms to the SOAP specifications. Write the elements in accordance with the SOAP and SAAJ specifications supported by the SOAP Communication Infrastructure. For details about the SOAP and SAAJ specifications supported by the SOAP Communication Infrastructure, see Chapter 12. in the manual Application Server SOAP Application Development Guide.

Exception

• Response to the service requester
  For details about how to acquire exception information, see the description of acquiring error information when a service requester is created.
  
• Response to the business process
  The business process cannot perform fault processing, so an exception is treated as an error (exception).
  

(e) Compiling

You must specify, for the class path, the following JAR file that is used for the custom adapter development framework, and then compile the file:

 
installation-directory-of-the-service-platform\CSC\lib\csc_adapter.jar.
 

If you use a service platform API, separately add and compile the necessary JAR files.

The general names of the JAR files created during custom adapter development are classified as follows:

• Protocol converter JAR files
  JAR files including the protocol converter class file and custom adapter development framework action definition file
  
• Library JAR files
  JAR files other than protocol converter JAR files
  

The following describes how to create individual JAR files.

(a) Creating protocol converter JAR files

Use the jar command to archive (to a JAR file) the protocol converter class file, the class file used by the protocol converter class file, and the custom adapter development framework action definition file.

The following shows the directory structure when necessary files are archived to a JAR file, and gives an example of specifying the jar command.

Directory structure of the JAR file

The following table describes the directory structure of the JAR file when files are archived by the jar command.

Table 3-82 Directory structure of JAR file when files are archived by the jar command

Directory name or file name	Description	Specification
/	Root directory in the archive	R
*.class	Stores the protocol converters and the class files (*.class) of classes (interfaces) that the protocol converters depend on, into the directory hierarchy that conforms to the package name.	R
framework_properties.xml	Specifies the class name (including the package name) of the protocol converter used by the custom adapter development framework.	R#
*	Any resource files used by the protocol converter. You can create a directory, in which to store files.	--
/META-INF/	Directory that stores management information. This directory is automatically created by the jar command.	--
MANIFEST.MF	The manifest file. This file is automatically created in the archive if the jar command is executed with the m option specified.	--

Legend:

R: Indicates that specification is required when files are archived.

--: Indicates that specification is not required (or optional) when files are archived.

#

If there are multiple JAR files, store this file only in the JAR file in containing the protocol converter.

Example of specifying the jar command when creating the JAR file

The following is an example of specifying the jar command when files are archived to a JAR file.

• Prerequisites
  Assume that the following files are in the current directory and sub directories:
  

  framework_properties.xml protocolconverter/CustomProtocolConverter.class lib/MyLib.class data/table.dat

• Example specification
  The following is an example of specifying the jar command when files are archived to a JAR file whose name is MyProtocolConverter.jar.
  

  jar cf ..\MyProtocolConverter.jar .\

(b) Creating library JAR files

Create library JAR files in the same way as general JAR files.

The following are notes on creating library JAR files.

File structure of a JAR file

Do not place files of the same name in multiple JAR files.

If there are files of the same name, the system cannot identify which used file belongs to which JAR file. Note that it is not a problem if only the directory name is the same.

The following table describes an example where two JAR files (A.jar and B.jar) are used, and their directory and file structures in a directory are the same.

Table 3-83 Example for when directory and file structures in the archive are the same

Structure of A.jar	Structure of B.jar	Description
myfile.txt	--	The file myfile.txt in A.jar is used.
samedata.dat	samedata.dat	It cannot be determined whether the used file samedata.dat is the file in A.jar or B.jar. Do not use the same file name.
dir/	dir/	You can use the same directory name.
--	dir/b.class	The file dir/b.class in B.jar is used.
dir/same.class	dir/same.class	Whether the used file def/same.class is the file in A.jar or B.jar cannot be determined. Do not use the same file name.

Legend:

--: Indicates that the file does not exist.

Arranging JAR files

Do not place a file with the name famework_properties.xml in the root directory of a JAR file.

If there is a JAR file with the name famework_properties.xml in the root directory, the file famework_properties.xml in the protocol converter JAR file might not be used.

Create an EAR file (necessary for registering a new custom adapter).

To create an EAR file, use the jar command to archive JAR files provided by the service platform to an EAR file.

The following shows the directory structure when JAR files are archived to an EAR file, and gives an example of specifying the jar command.

Directory structure of the EAR file

The following table describes the directory structure of the EAR file to which JAR files are archived by the jar command.

Table 3-84 Directory structure of the EAR file to which JAR files are archived by the jar command

Directory name or file name	Description	Specification
/	Root directory in the archive	R
cscmsg_adpejb.jar	Store the copy of the following file: installation-directory-of-the-service-platform\CSC\lib\cscmsg_adpejb.jar	R
/META-INF/	Directory that stores management information. This directory is automatically created by the jar command.	--
MANIFEST.MF	The manifest file. This file is automatically created in the archive if the jar command is executed with the m option specified.	--

Legend:

R: Indicates that specification is required when files are archived.

--: Indicates that specification is not required (or optional) when files are archived.

Note

Do not store files other than the above. If multiple JAR files are stored, you will not be able to register a custom adapter.

Example of specifying the jar command when creating an EAR file

The following is an example of specifying the jar command when files are archived to an EAR file.

• Prerequisites
  Store a copy of the following file in the current directory:
  installation-directory-of-the-service-platform\CSC\lib\cscmsg_adpejb.jar.
  
• Example specification
  The following is an example of specifying the jar command when files are archived to an EAR file whose name is CustomAdapter.ear.
  

  jar cf ..\CustomAdapter.ear .\

Set the EAR file when adding a custom adapter. If you need to modify the EAR file after adding a custom adapter, replace the EAR file in the Service Adapter Settings window of the custom adapter.

The EJB-JAR file names contained in the replacement EAR file must be the same as those (set when adding the custom adapter) in the EAR file. If the EJB-JAR file names are different, an error occurs when the EAR file is specified, and the EAR file cannot be set.

To replace the EAR file in the Service Adapter Settings window of the custom adapter:

1. On the Service Definition List in the tree view, double-click the custom adapter for which the EAR file is to be replaced.
   The Service Adapter Settings window appears.
   
2. Click the Service-adapter definition (details) tab at the bottom of the window.
   The Service Adapter Settings (details) window appears.
   
3. In the Service Adapter Definition (details) window, click the Browse button.
4. Specify the EAR file to be replaced.

To define a custom adapter:

1. Open the Service Adapter Settings window.
   For details about how to open the Service Adapter Settings window, see 3.3.1(4) Displaying the service adapter settings screen.
   
2. In Service component control information, edit Service name, Service ID, and Maximum instances, as necessary.
3. In Service component control information, click the Add button to add an operation.
   Specify the operation name designed in 3.3.14(1) Designing operations.
   
4. From the Operation drop-down list in Service component control information, select the operation you want to edit.
5. If necessary, select the Convert a system exception into a fault message check box in Service component control information.
6. From the Communication model drop-down list of the operation information, select Sync or Async.
   Specify the communication model designed in 3.3.14(1) Designing operations.
   
7. Perform the following operations:
   

   When specifying the standard message format

   Perform steps 8 to 12, and go to step 13.

   When not specifying the standard message format

   Go to step 13.

8. Click the >> button for the request message.
   The information fields for the standard message and data transformation definition are displayed.
   
9. Select the Use check box for the standard message.
10. Specify the Format ID for the standard message.
11. Click the Browse button for the standard message, and then specify the standard message format for Message format.
    For Message format, you can specify an XML message or binary message.
    
12. Click the Display button for the standard message.
    The format of the standard message is displayed. If necessary, check the format of the specified standard message.
    
13. Specify the Format ID for the service component message.
14. Click the Browse button for the service component message, and then specify the service component message format for Message format.
    Specify the message format designed in 3.3.14(1) Designing operations.
    For Message format, you can specify the XML message or binary message.
    
15. Click the Display button for the service component message.
    The format of the service component message is displayed. If necessary, check the format of the specified service component message.
    
16. Perform the following operations:
    

    When selecting the Use check box for the standard message

    Perform steps 17 to 19, and then go to step 20.

    When you do not select the Use check box for the standard message

    Go to step 20.

17. Enter the file name for the data transformation definition.
18. Click the Edit button.
    The Data-conversion definition screen appears.
    Note that, for the first definition, the Select Root Element dialog box appears.
    If you changed the message format, a dialog box appears, confirming whether to apply the change. For details, see 6.3.2 Procedure for defining changed message formats in the manual Service Platform Basic Development Guide.
    
19. Map the contents of the standard message and the contents of the service component message.
20. If, in step 6, you select Sync for Communication model, also perform steps 7 to 19 for the response message.
21. Click the Service-adapter definition (details) tab.
22. Check the name of the service adapter (EJB-JAR file).
    Make sure that the name is cscmsg_adpejb.jar.
    
23. Click the Add button for the utility class (JAR file), and register the JAR file.
    The file to be added is the JAR file you created in 3.3.14(5)(a) Creating protocol converter JAR files.
    If necessary, you can also add JAR files used by the protocol converter (such as library JAR files).
    
24. Click the Add button for the self-defined file, and add the following files, as necessary:
    
    • Self-defined file for protocol converter
    • Custom adapter property file
    • HITACHI Application Integrated Property File for custom adapter
25. If necessary, select a user-defined file, click the Edit button, and then edit the contents of the file.
26. Make sure that the definitions are correct, and from the Eclipse menu, select File and then Save to save the definitions.