Environment Configuration
This chapter describes the service information file, the WebService Gateway configuration file, and Tmax configuration file required for WebService gateway (WSGW) operation.
1. Service Information File
In order to use a Tmax service as a web service, the services that will be published externally need to be described. The definition files are used to convert SOAP messages from WSGW into Tmax buffer types and convert the service results to SOAP messages, or are used to create WSDL documents for service consumers.
The service definition is composed of the service information (name, input parameter type, and output parameter type) and input and output parameter information. The service is described in the SERVICE, REQUEST, and RESPONSE sections. The SERVICE section contains the service information, the REQUEST section contains the input parameter information, and the RESPONSE section contains the output parameter information.
Both REQUEST and RESPONSE sections must be defined to use the request-response method, and only REQUEST section is required to use the one-way method. Multiple number of services can be defined in a single file, which is case-sensitive. If the fields in the REQUEST or RESPONSE sections support internal structs, then they can use the data types from STRUCT section. For detailed information on each section’s configuration item, refer to Tmax Administration Guide.
The service information file is converted using the tmmbfgen utility before it is used in WSGW and xwsdlgen.
SERVICE Section
The following tables describe the items in the SERVICE section.
-
Required Items
Item Description name
External operation name.
-
Optional Items
Item Description tmaxname
Service name in Tmax. If not defined, then the value of the 'name' item is used.
intype
Input parameter type (STRING, CARRAY, STRUCT, FDL, char, short, int, float, or double). Omit if the input parameter does not exist.
outtype
Output parameter type (STRING, CARRAY, STRUCT, FDL, char, short, int , float, or double). Omit if the output parameter does not exist.
instruct
Struct name or user defined name when the input parameter type is STRUCT or FDL.
-
STRUCT: Configure the object name defined in SDL.
-
FDL: Determined arbitrarily by the user. If not set, it is automatically saved in the form of "ServiceNameRequestFDL".
outstruct
Object name or user defined name when the output parameter type is STRUCT or FDL.
-
STRUCT: Configure the object name defined in SDL.
-
FDL: Determined arbitrarily by the user. If not set, it is automatically saved in the form of "ServiceNameResponseFDL".
inalias
Name to use when the instruct name used in Tmax and the REQUEST name used in WebService are different.
outalias
Name to use when the outstruct name used in Tmax and the RESPONSE name used in WebService are different.
-
REQUEST and RESPONSE Sections
The following tables describe items in the REQUEST and RESPONSE sections.
-
Required Items
Item Description name
Parameter name.
type
Parameter type (char, int, long, float, double, string, carray, or struct).
-
Optional Items
Item Description maxoccurs
Maximum number of times the field can occur when all types (intype or outtype) are either STRUCT or FDL.
minoccurs
Minimum number of times the field can occur when all types (intype or outtype) are either STRUCT or FDL.
restriction
Same as the restriction items when converted to wsdl.
-
length, minLength, maxLength, enumeration, pattern, minExclusive, maxExclusive, minInclusive, maxInclusive, totalDigit, fractionDigit
(e.g., length="3", pattern="ab?")
subtype
Name of the struct when the type is STRUCT.
-
STRUCT Section
The following tables describe the items in the STRUCT section.
-
Required Items
Item Description name
Struct name.
TYPE
Defines the fields that are in the TYPE section.
-
TYPE Section Items
The following tables describe the TYPE section items inside the STRUCT section.
-
Required Items
Item Description name
Parameter name.
type
Parameter type (char, int, long, float, double, string, carray, struct).
-
Optional Items
Item Description maxoccurs
Maximum number of times the field can occur when all types (intype or outtype) are either STRUCT or FDL.
minoccurs
Minimum number of times the field can occur when all types (intype or outtype) are either STRUCT or FDL.
restriction
Same as the restriction items when converted to wsdl.
-
length, minLength, maxLength, enumeration, pattern, minExclusive, maxExclusive, minInclusive, maxInclusive, totalDigit, fractionDigit
(e.g., length="3", pattern="ab?")
subtype
Name of the struct when the type is STRUCT.
-
-
-
1.1. Binary Creation
tmmbfgen
A user-created service information file cannot be used in WSGW and xwsdlgen. A new file must be created using tmmbfgen. The file created by tmmbfgen is called the binary service information file. tmmbfgen can be used to validate grammar and parameter types before the file is referenced by WSGW, and to divide a text document into multiple files for management.
tmmbfgen can be used to:
-
Create a new binary service information file.
The following code is an example of creating a sample binary using the service information defined in sample1.txt and sample2.txt.
tmmbfgen -r sample1.txt,sample2.txt -o sample
-
Add service information to an existing binary service information file.
The following code is an example of adding the service information in sample3.txt to the existing sample file. If the new service information already exists in the sample file, then it overwrites the existing information.
tmmbfgen -i sample3.txt -o sample
-
Delete a specific service from the existing binary service information file.
The following code is an example of deleting the service information for SVC1 and SVC2 from the sample file.
tmmbfgen -d SVC1,SVC2 -o sample
untmmbfgen
untmmbfgen is used to revert the binary service information file into a text file that users can understand.
untmmbfgen -i sample -o unsample.txt
1.2. Example
This section describes how to configure a service information file according to each message type.
STRING Type
This service accepts a string and converts it to uppercase.
-
input parameter: char[20]
-
output parameter: char[20]
The following is a sample code of the TOUPPER service information file.
SERVICE name = TOUPPER intype = STRING outtype = STRING REQUEST name = req type = string RESPONSE name = result type = string
STRUCT Type
This service accepts a string length and the structure that contains the string and converts it to uppercase.
-
Input parameter: kstrdata
-
Output parameter: kstrdata
The following is a sample code of the TOUPPERSDL service information file.
SERVICE name = TOUPPERSDL intype = STRUCT outtype = STRUCT instruct = kstrdata outstruct = kstrdata REQUEST name = len type = int name = str type = string RESPONSE name = len type = int name = str type = string
The following is a sample code of the SDL file.
struct kstrdata {
int len;
char sdata[20];
}
FIELD Type
This service accepts a string field and converts it to uppercase.
-
Input parameter: field INPUT
-
Output parameter: field OUTPUT
The following is a sample code of the TOUPPERFDL service information file.
SERVICE name = TOUPPERFDL intype = FDL outtype = FDL instruct = toupfdl outstruct = toupfdl REQUEST name = INPUT type = string RESPONSE name = OUTPUT type = string
The following is a sample code of the FDL file.
INPUT 101 string - - OUTPUT 102 string - -
2. WebService Gateway Configuration File
At WSGW startup, the gateway reads the WSGW configuration file to determine the IP address and port number of the HTTP listener for Tmax service. The WSGW configuration file, which is also used by xwsdlgen, includes a list of Tmax services to provide and an HTTP address to bind to.
2.1. File Format
The WSGW configuration file is configured in XML with <Configuration> as the root element. The sub elements are configured beneath <in> when acting as a web service provider, and beneath <out> when acting as a service consumer.
<in>
The <in> element has the sub elements <Servicelist>, which describes the services to provide, and <GWInstance>, which describes the address to bind to.
-
<Servicelist>
Describes the services to provide using the <service> sub element.
<Servicelist id=”sample”> <service name=”TOUPPER” /> <servicename=”TOUPPERSDL” /> </Servicelist>Property Description id
Name of the service list. Used as the namespace when creating a WSDL document.
-
<service>
Displays the name of a service to provide.
Property Description name
Uses the "name" value of the SERVICE section in the service information file.
wswns
Used as the namespace of the root element when creating the WSDL file.
typens
Used as the namespace of the type-related element when creating the WSDL file.
-
-
<GWInstance>
<GWInstance> <HTTP address="127.0.0.1:10032"/> </GWInstance>
-
<HTTP>
Property Description address
HTTP address and the port number that WSGW will listen to.
-
<out>
The <out> element has the sub element <Servicelist>, which describes the services to call, and the location to connect to as its property.
-
<service>
Displays the name of a service to call.
Property Description uri
Address of the web service provider.
soap_version
SOAP version (1.1, 1.2) to request.
encoding_style
rpc or doc
wsns
Namespace of the root element of the WSDL document.
typens
Namespace of the data type of the WSDL document.
-
<Servicelist>
Displays the services to call.
<Servicelist id=”sample”> <service name=”TOUPPER” /> <servicename=”TOUPPERSDL” /> </Servicelist>-
<service>
Displays the name of a service to call.
Property Description name
Name to use for the "name" item of the SERVICE section in the service information file.
-
2.2. Example
The following code shows the gateway configuration file for TOUPPER, TOUPPERSDL, TOUPPERFDL services.
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="http://www.tmax.co.kr/twsp/twsgwconfig/">
<in>
<Servicelist id="TmaxSampleECHO" >
<Service name="TOUPPER_TMAX" />
</Servicelist>
<GWInstance>
<HTTP address="192.168.1.43:5001"/>
</GWInstance>
</in>
<out uri="http://192.168.11.240:80/axis2/services/TmaxSampleTouppers"
soap_version = "1.2" encoding_style="rpc"
wsns = "http://192.168.11.240:80/axis2/services/TmaxSampleTouppers"
typens= "">
<Servicelist>
<Service name="TOUPPER" />
<Service name="TOUPPERFDL" />
</Servicelist>
</out>
<out uri="http://192.168.11.240:80/axis2/services/RPCSample"
soap_version = "1.1" encoding_style="rpc"
wsns= "http://192.168.11.240:80/axis2/services/RPCSample/RPCSample"
typens= "http://192.168.11.240:80/axis2/services/RPCSample/RPCSampleType">
<Servicelist>
<Service name="TOUPPERSDL" />
</Servicelist>
</out>
</Configuration>
3. Tmax Environment Configuration
WSGW configuration follows the GATEWAY section of the Tmax environment configuration, and the required items are GWTYPE, CLOPT(-c,-m), NODENAME, and DIRECTION.
The following is a sample code of the Tmax environment configuration file.
*SERVICE
TOUPPER SVRNAME = WSGWOUT
TOUPPERSDL SVRNAME = WSGWOUT
TOUPPERFDL SVRNAME = WSGWOUT
*GATEWAY
WSGWOUT
GWTYPE=WSGW,
NODENAME=tmaxi4,
PORTNO=5005,
RGWADDR="192.168.11.240",
RGWPORTNO=80,
DIRECTION=OUT,
CLOPT="-csample.xml -msample",
CPC=3
The following describes the required Tmax environment configuration items.
| Item | Description |
|---|---|
GWTYPE |
Must be set to WSGW. |
CLOPT |
Must set the web service configuration file and binary service information file names to use. These files must exist in $TMAXDIR/config. |
NODENAME |
Node name where WSGW is installed. |
DIRECTION |
For the web service provider, enter IN. For the web service consumer, enter OUT. |
PORTNO |
Listening port number. |