To operate an HTTP adapter in the execution environment, add the library (cjjaxrs.jar) of JAX-RS to the class path of a J2EE server. Edit the option definition file for a J2EE server (usrconf.cfg) and describe the following contents:

add.class.path=Installation directory of the service platform\jaxrs\lib\cjjaxrs.jar

For details on the option definition file for the J2EE server (usrconf.cfg), see 2.3 usrconf.cfg (option definition file for a J2EE server) in the manual Application Server Definition Reference Guide.

The types, formats, and methods to create message formats to be used in the HTTP adapter are described here.

(a) Message format type

The following table describes the message format types to be used in the HTTP adapter:

Table 3-75 Message format types

Legend:

Y: Created by User.

A: Can be edited, if necessary.

N: Cannot be edited. Operations to be performed on editing the message format are not guaranteed.

(b) Message format

The formats of a request message, a response message, and a fault message used in the HTTP adapter are described here.

adphttp_header_request1.xsd/adphttp_header_request2.xsd (request message format (for header variable))

The following table describes the request message format of a header variable, which is passed on to an HTTP adapter by a business process. Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_request".

Table 3-76 Request message format (for header variables)

Tag name					Type	Occurrence count	Description
<http-header-request>					-	1 time	-
	<request-id>				string	0 or 1 time	Set the request ID generated in the HTTP reception or the FTP reception.Required to send the file data in the working folder.and to receive a file in the working folder.
	<method>#1				string	0 or 1 time	Specify the HTTP method of the request line. You can specify any of the following values: GET HEAD POST OPTIONS PUT DELETE If you set any other value, operations are not guaranteed.
	<uri-scheme-authority>#1				string	0 or 1 time	Specify the scheme and the authority (upto the port number of URI) of URI of the request line. URL encoding of the value is not performed. It becomes the first character string when composing the URI.
	<uri-path>#1				string	0 or 1 time	Specify the path of the URI of the request line. As a general rule, you must specify "/" at the beginning of the specified character string, since this string is connected immediately after the uri-scheme-authority element. You need not specify "/" in the case of root path ("/").
	<uri-query>				string	#2	Specify the request line query.
	<http-header-Authorization>#1				string	0 or 1 time	Specify the authentication information corresponding to the Authorization header of the HTTP request header. Specify the authentication type in the type attribute: When you send the authentication information Specify the type attribute in raw, and then specify the header field value of the Authorization header in this element. When you do not send the authentication information Specify none in the type attribute. Even if you specify a value in this element, it is ignored. Authorization header is not set in the HTTP request header. If you specify any other value in the type attribute, an error occurs.
	<http-header-Content-Type>#1				string	0 or 1 time	Specify the media type corresponding to the Content-Type header of the HTTP request header. Specify the character code corresponding to the charset attribute of the Content-Type header in the charset attribute.
	<http-header-Cookies>				- (any)	0 or 1 time	Specify the Cookie information of the HTTP request. Schema files to be used differ depending on whether you set Cookie elements in a batch or individually: When you set Cookie elements in a batch Use the schema file adphttp_header_request1.xsd. Specify the Cookie information with any type. When you set Cookie elements individually Use the adphttp_header_request2.xsd schema file. Specify respective Cookie information in the Cookie elements.
		<Cookie>			string	0 or more	Specify the Cookie information of the HTTP request in the format of the Set-Cookie header passed from the HTTP response for each Cookie information. Specify the Cookie name of the Set-Cookie header of the HTTP response in the name attribute. Specify the host name (domain) of the server that sends the Cookie of the Set-Cookie of the HTTP response in the host attribute. Specify the path of the server that sends the Cookie of the Set-Cookie header of the HTTP response in the path attribute. For the value of each attribute and element of Cookie elements, use the value of Cookie elements of the response message (header) in which the Cookie information to be inherited is stored. If you set any other value, operations to be performed are not guaranteed.
	<http-header>				-	0 or 1 time	Specify the HTTP header information.
		Any element#1			string	0 to 1,024 times	Specify the HTTP header information such that the header field name is to be specified in the element name and the header field value is to be specified in the element value. This is ignored if the hierarchical structure and attribute value are specified, and also when some particular header information is specified. For details, see 2.14.3 Relationship between HTTP requests and request messages in the manual Service Platform Overview.
	<http-part>				-	0 or 1 time	Specify the meta information of parts.
		<message>			-	0 or 1 time	Specify the information related to request messages (body).
			<binding>#1		string	1 time	Specify any of the following methods as the method to process a request message (body): none Sends HTTP requests when the request message (body) is not present. When you specify this value the Content-Type header of the HTTP request is not set. raw Sends the contents of the request message (body) as-is as the pass-through mode. The Media type and the character code specified in the http-header-Content-Type element are set in the Content-Type header. form-data As the normal mode, this method converts and sends the request message (body) to the form data format. application/x-www-form-urlencoded is set in the Content-Type header of the HTTP request. The character code specified in the http-header-Content-Type element is set in the character code. Other than the above A system exception occurs.
		<files>			-	0 or 1 time	Specify the file information sent with the HTTP request. If you specify this element, even if the request message (body) is already set, the content specified in this element takes precedence.
			<file>		-	0 or more	Specify the information related to the file to be sent. If you specify this element for more than 2 times, the element acquired first is considered as valid.
				<input-folder-name>#1	string	1 time	Specify any of the following folders as the folder to store the file to be sent: For a working folder Specify null. (An error does not occur even if you specify a null string). For a common folder Specify the common folder definition name. You can specify the following values to identify the folder in which the file to be sent exists in the common attribute. For a working folder Specify "common="false"". For a common folder Specify "common="true"". Note that an error occurs at the time of reading if the specified folder is invalid or is a symbolic link.
				<local-file-name>#1	string	1 time	Specify name of the file to be sent: When you specify a working folder in the input-folder-name element Specify the intermediate file name in the working folder. When you specify a common folder in the input-folder-name element Specify the file name in the common folder. If a file with the specified name does not exist, a system exception occurs. In addition, an error occurs in the following cases: If specification ("/../") related to password change is included If the specified file name is invalid If symbolic link is included
	<output-folder-name>#1				string	0 or 1 time	Specify any of the following folders as the folder to output the downloaded file at the time of the HTTP response: For a working folder Specify null. (An error does not occur even if you specify a null string). For a common folder Specify the common folder definition name. You can specify the following values to identify the folder in which the file to be sent exists in the common attribute. For a working folder Specify "common="false"". For a common folder Specify "common="true"". Note that an error occurs at the time of writing if the specified folder is invalid or is a symbolic link.

Legend:

-: There is no corresponding item.

Note#1

If there is no specification of elements, the specification of the HTTP-adapter runtime-environment property file or the HTTP-adapter runtime-environment common property file becomes valid.

For the corresponding relationship between a request message and a property file, see 2.14.13 Corresponding relationship between request message (header) and HTTP adapter execution environment (common) properties file in the manual Service Platform Overview.

Note#2

Follows the specification of the detailed message format for the query of include destination.

adphttp_header_query_detail.xsd (detailed message format for a query)

The following table describes the detailed message format for the query included in the request message format (for header variables). Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_request".

Table 3-77 Detailed message format for a query

Tag name		Type	Occurrence count	Description
<uri-query>		-	0 or 1 time	-
	Any element #	string	0 to 1,024	Set the detailed information of the request line query.

Legend:

-: There is no corresponding item.

Note#

If there is no specification of elements, the specification of the HTTP-adapter runtime-environment property file or the HTTP-adapter runtime-environment common property file becomes valid.

For the corresponding relationship between the request message and the property file, see 2.14.13 Corresponding relationship between request message (header) and HTTP adapter execution environment (common) properties file in the manual Service Platform Overview.

adphttp_body_empty.fdx (message format for file data)

The following table describes the message format for the file data indicating an empty HTTP message body:

Table 3-78 Message format for file data

Simple content element		Type	Occurrence count	Description
<http-body-common-empty>		-	1 time	-
	<data>	String	0 or more	Specifies an element used to pass an empty data. You can omit this element.

Legend:

-: There is no corresponding item.

adphttp_body_form-data.xsd (message format for the form data)

The following table describes the message format for the form data passed on to an HTTP adapter to a business process. Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/body_form_data".

Table 3-79 Message format for the form data

Simple content element		Type	Occurrence count	Description
<http-body-form-data>		-	1 time	-
	Any element	String	0 or more	Specify any element according to the form data sent with the HTTP request body.

Legend:

-: There is no corresponding item.

adphttp_header_response1.xsd/adphttp_header_response2.xsd (response message format (for header variable))

The following table describes the response message format of header variables returned to a calling business process by an HTTP adapter. Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/header_response".

Table 3-80 Response message format (for header variable)

Tag name					Type	Occurrence count	Description
<http-header-response>					-	1 time	-
	<request-id>				string	0 or 1 time	The request ID specified in the request message is set. If you do not specify a request ID in the request message, this element is not generated.
	<status-code>				string	1 time	The status code of the status line of the HTTP response is set.
	< reason-phrase>				string	1 time	The reason phrase part of the status line is set.
	<http-header-Content-Type>				string	0 or 1 time	The media type of the Content-Type header is set.
	<http-header-Cookies>				- (any)	1 time	The Set-Cookie header of the HTTP response is set. Schema files to be used differ depending on whether you set Cookie elements in a batch or individually. When you set Cookie elements in a batch Use the schema file adphttp_header_response1.xsd. Specify the Cookie information in a batch with any type. When you set Cookie elements individually Use the schema file adphttp_header_response2.xsd. Specify each Cookie information in the Cookie elements.
		<Cookie>			string	0 or more	The Set-Cookie header of the HTTP response is stored for each Cookie information. The Cookie name of the Set-Cookie header of the HTTP response is set in the name attribute. The host (domain) name of the server that sends the Cookie of the Set-Cookie header of the HTTP response is set in the host attribute. The path of the server that sends the Cookie of the Set-Cookie header of the HTTP response is set in the path attribute.
	<http-header>				-	1 time	The HTTP response header is stored.
		Any element			string	0 or more	The HTTP header information is set such that the header field name is specified in the element name and the header field value is specified in the element value.
	<http-body>				-	1 time	The HTTP response body information is set.
		<output-folder-name>			string	0 or 1 time	The output destination folder of the files downloaded with the HTTP response is set. The value of the output destination folder is same as the value specified in the output-folder-name element of the request message format (for header variables) For a working folder Null is set. For a common folder The common folder definition name is specified. The values to identify the folder in which the file to be sent exists are set in the common attribute. For a working folder "common="false"" is set. For a common folder "common="true"" is set. If there are no files to be downloaded, this element is not generated.
	<http-part>				-	1 time	The meta information of parts is set.
		<files>			-	0 or 1 time	The file information received with the HTTP response is set.
			<file>		-	1 time	The information of the file to be received is stored.
				<local-file-name>	string	1 time	Name of the file output to a common or a working folder is set. If the output folder is a common folder A name that is unique in the HTTP adapter is set for the file, which is output. If the output folder is a working folder Name of an intermediate file, which is output, is set.
				<file-name>	string	0 or 1 time	The value specified in the filename attribute of the Content-Disposition header is set. If the filename attribute is not present, this element is not generated.
	<context>				-	1 time	The execution information of the HTTP adapter is stored.
		<adapter-name>			string	1 time	The name of the adapter that has sent an HTTP request that is the basis of this HTTP response is set.
		<operation-name>			string	1 time	Name of the operation of sending an HTTP request that is the basis of this HTTP response is set.
		<request-method>			string	1 time	The method type of the HTTP request that is the basis of this HTTP response is set.
		<request-uri>			string	1 time	URI (Authorization, Path excluding Scheme and UserInfo) of the HTTP request that is the basis of this HTTP response is set.

Legend:

-: There is no corresponding item.

adphttp_fault.xsd (fault message format)

The following table describes the fault message format of header variables returned by the HTTP adapter to a calling business process. Name of the name space is "http://www.hitachi.co.jp/soft/xml/cosminexus/csc/adapter/http/fault".

Table 3-81 Fault message format

Tag name			Type	Occurrence count	Description
<http-fault>			-	1 time	-
	<status-code>		string	1 time	The status code of the status line of an HTTP response is set.
	< reason-phrase>		string	1 time	The reason phrase part of the status line is set.
	<http-header>		-	1 time	The HTTP response header is stored.
		Any element	string	0 or more	The HTTP header information is set such that the header field name is specified in the element name and the header field value is specified in the element value.
	<context>		-	1 time	The execution information of the HTTP adapter is stored.
		<adapter-name>	string	1 time	The name of the adapter that has sent the HTTP request which is the basis of this HTTP response is set.
		<operation-name>	string	1 time	The name of the operation of sending an HTTP request which is the basis of this HTTP response is set.
		<request-method>	string	1 time	The method type of the HTTP request that is the basis of this HTTP response is set.
		<request-uri>	string	1 time	URI (Authorization, Path excluding Scheme and UserInfo) of the HTTP request that is the basis of this HTTP response is set.

Legend:

-: There is no corresponding item.

(c) Method to create the message format

The method to create the message format used in the HTTP adapter is described here.

The XML schema of the message format provided by the service platform is stored in "Installation directory of the service platform\CSC\custom-adapter\HTTP\schema".To edit, first copy folder-wise contents at any location, and then edit.

The method to create the following formats is as follows:

• Detailed message format for a query
• Message format for form data
• Message format for the pass-through mode
  
  

Creating Detailed message format for a query

1. Open the XML schema file (adphttp_header_query_detail.xsd) with the XML editor, and edit in the following manner:
   

   

   Change the xsd:any type element to the xsd:string type element for which the query name is the local name. You can specify any value as the occurrence count.
   

   Note

   The upper limit of the query elements that you can specify directly under the uri-query element is upto 1,024. If you specify 1,025 or more elements, operations are not guaranteed.

2. Overwrite and save the XML schema file.
   
   

Creating the Message format for form data

1. Open the XML schema file (adphttp_body_form-data.xsd) with the XML editor , and edit in the following manner:
   

   

   Change the xsd:any type element to the xsd:string type element for which the local name is the key name of form data. You can specify any value as the occurrence count.
   
2. Overwrite and save the XML schema file.
   
   

Creating the message format for the pass-through mode

1. Create any message format with the editor.
2. Save with any file name.
   
   

   Note

   • You can specify any one type among XML type, on-XML type, and any type for the variable type. However, in the case of XML type, you must create the message format of the XML format definition file and in the case of non-XML type, you must create the message format of the binary format definition file.
   • You can specify the character code of the HTTP request body with the charset attribute of the Content-Type header. However, do not convert this character code to the character code specified in the HTTP adapter. Therefore, you must perform the character code conversion yourself, before setting up the body data in the request message (body).

The procedure for defining HTTP adapters is as follows:

1. Display the service adapter settings screen.
   For details on how display the service adapter settings screen, see 3.3.1(4) Displaying the service adapter settings screen.
   
2. Set the definition information on the service adapter settings screen (basic).
   For details on the items that you must set on the service adapter settings screen (basic), see 3.3.15(11) For HTTP adapters and 1.2.2 Service Adapter Definition Window in the manual Service Platform Reference Guide.
   
3. Click the [Service adapter definition (details)] tab.
   The service adapter settings screen (details) is displayed.
   
4. Set the definition information on the service adapter settings screen (details).
   For details on the items that you must set in the service adapter settings screen (details), see 3.3.15(11) For HTTP adapters.
   

The following are the types of the definition files to be created and edited:

• HTTP-adapter definition file
  This file is used for setting the operation information of the HTTP adapter.
  
• HTTP-adapter runtime-environment property file
  This file is used for setting the configuration information for each HTTP adapter.
  
• HTTP-adapter runtime-environment common property file
  This file is used for setting the common configuration information in all HTTP adapters.
  

Note that the creation and editing of these definition files is optional. If omitted, the default value for each definition file is used.

The procedure for creating and editing each definition file is as follows:

(a) HTTP-adapter definition file

Edit the HTTP-adapter definition file by using the template file provided by the service platform.

The procedure for editing the HTTP-adapter definition file is as follows:

1. In the [Self-defined file] of the Service adapter settings screen (details), select "cscadphttp.properties", and click the [Edit] button.
   The editor used for editing the HTTP-adapter definition file is started.
   
2. Edit the HTTP-adapter definition file using the editor.
   For details on the definition contents that you can edit in the HTTP-adapter definition file, see HTTP-adapter definition file in the manual Service Platform Reference Guide.
   
3. From the Eclipse menu, select [File]- [Save], and then save the definition content.

(b) HTTP-adapter runtime-environment property file

1. Copy the template file (Installation directory of the service platform\CSC\custom-adapter\HTTP\config\templates\serviceid.properties), and save this file in the following directory:
   Installation directory of the service platform\CSC\custom-adapter\HTTP\config
   
2. Change the file name of the copied template file to "<Service ID#>.properties".
3. Edit and save the definition content.

For details on the definition contents that you can edit in the HTTP-adapter runtime-environment property file, see HTTP-adapter runtime-environment property file in the manual Service Platform Reference Guide.

Note

The service ID is any string that you specify in the service adapter setting screen when adding a new HTTP adapter.

The HTTP-adapter runtime-environment property file is reflected in the execution environment when you start an HTTP adapter. Therefore, to change the contents of the HTTP-adapter runtime-environment property file, you must stop the HTTP adapter once.

(c) HTTP-adapter runtime-environment common property file

1. Copy the template file (installation directory of the service platform\CSC\custom-adapter\HTTP\config\templates\adphttpcom.properties), and save this file in the following directory:
   Installation directory of the service platform\CSC\custom-adapter\HTTP\config\common
   Do not change the file name.
   
2. Edit and save the definition contents.

The definition contents that you can edit in the HTTP-adapter runtime-environment common property file are same as the contents of the HTTP-adapter runtime-environment property file. For details, see HTTP-adapter runtime-environment common property file in the manual Service Platform Reference Guide.

HTTP-adapter runtime-environment common property file is reflected in the execution environment, when you start an HTTP adapter. Therefore, to change the contents of the HTTP-adapter runtime-environment common property file, you must stop the HTTP adapter once.

If settings such as the proxy server or connection inheritance are required, set it using the system property file (usrconf.cfg).For details on the properties to be set in the HTTP adapter, see 2.14.6 Communication through proxy servers in the manual Service Platform Overview and 2.14.7 Communication using connection continuity (Keep-Alive) in the manual Service Platform Overview.

If you use an HTTP adapter, you must set the invoke service activities and fault processing, if necessary.

The following is the method to set the invoke service activities and fault processing:

(a) Settings of the invoke service activities

Defines the invoke service activities to invoke the HTTP adapter. For details on how to define the invoke service activities, see 5.6.4 Invoke service activity in the manual Service Platform Basic Development Guide.

The settings of the [Invoke service activities] dialog box are as follows:

Note#1

You must initialize the variable before invoking the service.

Note#2

If you do not want to use the request message (header) or the response message (header), setting is not required.

Note#3

Null string is set after invoking the service.

(b) Settings of the fault processing

If you process a system exception that is converted to a status code or a fault that you cannot process as a normal node, as an error in the business process, define the fault processing in the invoke service activity and in the upper-level scope. For details on the method to define the fault processing, see 5.4.3 Defining Fault Handling in the manual Service Platform Basic Development Guide.

The settings of the [Assign the fault processing] dialog box are as follows: