uCosminexus Application Server, Web Service Development Guide

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

14.3 cjwsgen command

The cjwsgen command generates the Java code (JavaBean classes) and resource files (WSDL and XSD) that are required to deploy Web Services, based on the class files of the Service Implementation Class. Note that a Service Implementation Class also includes the classes and SEIs that are referenced by the Service Implementation Class.

This section describes the format and specification contents for executing the cjwsgen command.

Organization of this section
(1) Format
(2) List of options
(3) Generated files
(4) Relationship between the Input Service Implementation Class and output resource files
(5) Operation during processing
(6) End codes
(7) Action for abnormal termination

(1) Format

The following is the specification format of the cjwsgen command:

cjwsgen [Options] Fully qualified name of the Service Implementation Class

Specification examples
  • Checking the WSDL before deploying:
    cjwsgen -wsdl -cp . com.example.UserInfoImpl
  • Generating the Java code and resource files of a Web Service (SOAP 1.2) from an existing Web Service (SOAP 1.1):
    cjwsgen -soap 1.2 -cp . com.example.UserInfoImpl
  • Generating the Java code and resource files of a Web Service (with service name MyService) from an existing Web Service:
    cjwsgen -servicename {http://example.com/}MyService -cp . com.example.UserInfoImpl
  • Generating the Java code and resource files of a Web Service (with port name MyServicePort) from an existing Web Service:
    cjwsgen -portname {http://example.com/}MyServicePort -cp . com.example.UserInfoImpl

Notes for executing the cjwsgen command
You cannot assume a current directory with the characters such as &, and ^ to execute the cjwsgen command. If you assume such a current directory and execute the command, the operations will not be guaranteed.
Check that source files other than the source files generated by the cjwsgen command do not exist under the following directories:
  • When you output a source file: the output destination directory of the source file
  • When you do not output a source file : the work directory used by the cjwsgen command
For details on the output destination and the work directory of a source file, see Combination of the -d, -s, and -keep options and the output destination directory and the work directory.

Notes for specifying the Service Implementation Class
  • Deploy the source files of the Service Implementation Class in a directory different from the class files. If you deploy the source files in the same directory as the class files, an error might occur.
  • Specify the class files of the Service Implementation Class with their fully qualified names in the arguments.
  • If you do not specify the arguments, an error message will output to the standard error output and logs, and the processing will end (KDJW71023-E).
  • If you specify other than a class file in the arguments, an error message will output to the standard error output and logs, and the processing will end (KDJW71026-E).
  • If you specify other than the Service Implementation Class in the arguments, an error message will output to the standard error output and logs, and the processing will end (KDJW71025-E).
  • If the specified Service Implementation Class is not found, an error message will output to the standard error output and logs, and the processing will end (KDJW71026-E).
  • If you do not have the access privileges for the specified Service Implementation Class, an error message will output to the standard error output and logs, and the processing will end (KDJW71026-E).
  • If you specify a Service Implementation Class in which the javax.jws.WebService annotation is not specified, an error message will output to the standard error output and logs, and the processing will end (KDJW71029-E).
  • If you specify multiple classes containing the Service Implementation Class in the arguments, a warning message will output, and the processing will continue (KDJW71027-W). To confirm which Service Implementation Class was handled effectively, see the warning message.
  • Do not specify the Service Implementation Class acting as an inner class in an argument. If you specify, the operation is not guaranteed.
  • For details about the notes related to SEIs and Web Service Implementation Classes other than the above, see the 16.1 Default mapping of Java to WSDL and 16.2 Customized mapping of Java to WSDL sections.

(2) List of options

You can specify the options listed in the following table for the cjwsgen command:

Table 14-6 List of options of the cjwsgen command

Option Set item Specification contents
-d directory Path of the output destination directory of already compiled class file Specifies the output destination directory of the already compiled class file (*.class).
For details about the values that you can specify, see Notes for specifying the -d, -s, and -r options described outside the table.
If you specify any other option, a file other than the already compiled class file might be output to the directory specified in this option. For details, see Combination of the -d, -s, and -keep options and the output destination directory and the work directory and Combinations and output destination directory of the -d, -r, -soap, -servicename, -portname, -soap12binding, and -wsdl options described outside the table.
-s directory Path of the output destination directory of the source file Specifies the output destination directory, when you output the source file (*.java).
-r directory Path of the output destination directory of the resource files Specifies the output destination directory when you output the resource files (*.wsdl and *.xsd).
-keep None Specifies whether or not to maintain the source file (*.java).
-wsdl None Specifies whether or not to output the resource files (*.wsdl and *.xsd).
-soap version Version of SOAP binding Specifies the version of SOAP binding used by the Web Service during communication.
-servicename service-name Service name Specifies the service name after making changes.
-portname port-name Port name Specifies the port name after making changes.
-soap12binding soap-spec Value indicating the URL set in the transport attribute of the soap12:binding element Specifies the URL to be set in the transport attribute of the soap12:binding element (child element of the wsdl:binding element) for SOAP1.2.
-classpath class-path Class path that includes the Service Implementation Class Specifies the class path that includes the Service Implementation Class specified in the argument.
-cp class-path
-verbose None Specify this option to output the detailed processing progress, when executing a command.
-help None Specify this option to display Help.
If you specify this option, all options except -version are ignored, Help is displayed, and the processing terminates.
-version None Specify this option to display the version information.
If you specify this option, the other options are ignored, the version information is displayed, and the processing terminates.

The following are the notes on the specification values of options, such as the values that you can specify in an option and the operation executed when you omit an option:

Notes common to options
The notes common to all options are as follows:
  • The specification order of options and arguments is optional. The specification order of each option is also optional.
  • Always specify the arguments for options with arguments. If you do not specify the arguments, an error message will output to the standard error output and logs, and the processing will end (KDJW71001-E).
  • If you specify the same option more than once, the option specified last will be valid. However, if you specify an invalid value for an option, an error will occur.
  • The specification of an option is case sensitive.
  • The length of the character string to be specified is not limited. However, an error occurs when you exceed the limit specified for the OS.
  • If you specify a file path containing a blank space in the option, enclose the entire path within double quotation marks (""). If you do not enclose the entire path within double quotation marks (""), the operations are not guaranteed.
  • If you specify an option that you cannot specify, an error message will output to the standard error output and logs, and the processing will end (KDJW71001-E).

Notes for specifying the -d, -s, and -r options
The following are the notes related to the specification values of the -d option, -s option, and -r option:
  • The specification value is not case sensitive.
  • If the specified output destination directory does not exist, an error message will output to the standard error output and logs, and the processing will end (KDJW71002-E).
  • If you specify the file in the wrong output destination directory, an error message will output to the standard error output and logs, while Help will output to the standard output, and the processing will end (KDJW71003-E).
  • Do not use the following characters in the path of the output destination directory to be specified in the -d option. If you use the following characters, the operations are not guaranteed:
    # % & ^ ; ` { } [ ]
  • Do not use the following characters in the path of the output destination directory to be specified in the -r option. If you use the following characters, the operations are not guaranteed:
    % & ^ ` { } [ ]
  • Do not use the following characters in the path of the output destination directory to be specified in the -s option. If you use the following characters, the operations are not guaranteed:
    & ^
  • If you specify a directory for which you do not have the access privileges, a JDK error will occur and the processing will end.

Notes for specifying the -soap option
The following are the notes related to the specified values of the -soap option:
  • You can specify only 1.1 or 1.2 as the version of the SOAP binding. If you specify any other value, an error message will output to the standard error output and logs, while Help is output to the standard output, and the processing will end (KDJW71004-E).
  • If you have specified a value in both the -soap option and the javax.xml.ws.BindingType annotation, priority is given to the value of the -soap option.
  • If you omit the -soap option, the specification values of the javax.xml.ws.BindingType annotation become enabled.
  • If you specify 1.1 in the -soap option when the specification value of javax.xml.ws.BindingType is the SOAP 1.2 over HTTP binding, an error message will output to the standard error output and logs, and the processing will end (KDJW71007-E).

Notes for specifying the -servicename option
Code the -servicename option in the QName format. The following is a coding example of the -servicename option:
{Namespace URI}Service name
Namespace
  • Enclose the namespace URI within a parentheses ({ }). If you omit the namespace or do not enclose within the parentheses ({ }), an error message will output to the standard error output and logs, and the processing will end (KDJW71009-E).
  • If you do not close the parentheses, an error message will output to the standard error output and logs, and the processing will end (KDJW71008-E).
  • If you do not enter a value within the parentheses ({ }), an error message will output to the standard error output and logs, and the processing will end (KDJW71008-E).
  • Specify single-byte alphanumeric characters for the namespace URI. If you specify other than the single-byte alphanumeric characters, the operations are not guaranteed.
Protocol
  • Only a domain name beginning with http:// or urn: is valid as the namespace URI to be coded in the -servicename option. The namespace URIs beginning with https:// and file:// are handled as invalid. If you specify a namespace URI beginning with other than http:// or urn:, an error message will output to the standard error output and logs, and the processing will end (KDJW71011-E).
  • You cannot specify a relative path for the namespace URI to be coded in the -servicename option. If you specify a relative path for the namespace URI, an error message will output to the standard error output and logs, and the processing will end (KDJW71012-E).
Information that you cannot specify
You cannot code query strings, anchors, port numbers, user names, and passwords in the namespace URI to be coded in the -servicename option. If you specify this information in the namespace URI, an error message will output to the standard error output and logs, and the processing will end (KDJW71013-E).
Character strings that you can code
In a segment demarcated with the delimiters such as a forward slash (/) or a period (.), you can code a character string that satisfies all the conditions described in the following table:

Table 14-7 Conditions for character strings that you can code in a namespace (When you specify the -servicename option)

No. Condition Examples of invalid character strings Operation when an invalid character string is specified
1 Character strings using only single-byte alphanumeric characters (0 to 9, A to Z, and a to z) http://hitachi.com/
http://133.145.224.19/
http://[1080:2C14;D30:BA04:275:806:270C:418A]/		 The operation is not guaranteed (no error message is displayed).
2 Character strings containing other than reserved terminology of Java http://hitachi.com/abstract The operation is not guaranteed.
3 Character strings that do not begin with a numeric character http://1hitachi.com
Service name
  • If you omit the service name, an error message will output to the standard error output and logs, and the processing will end (KDJW71014-E).
  • Specify single-byte alphanumeric characters and underscores for a service name. If you specify other than the single-byte alphanumeric characters and underscores, the operations are not guaranteed.
  • We recommend that you specify a service name in accordance with the identifier naming rules stipulated in Java. If the specified service name is not in accordance with the identifier naming rules stipulated in Java, a compilation error occurs when you execute the cjwsimport command to develop the Web Service client.

Notes for specifying the -portname option
Code the -portname option in QName format. The following is a coding example of the -portname option:
{Namespace URI}Port name
Namespace
  • Enclose the namespace URI within a parenthesis ({ }). If you omit the namespace or do not enclose within parentheses ({ }), an error message will output to the standard error output and logs, and the processing will end (KDJW71016-E).
  • If you do not close the parentheses, an error message will output to the standard error output and logs, and the processing will end (KDJW71015-E).
  • If you do not enter a value within the parentheses ({ }), an error message will output to the standard error output and logs, and the processing will end (KDJW71015-E).
  • Specify a namespace URI same as that of the service element of the WSDL file. If you specify a namespace URI different from that of the service element of the WSDL file, an error message will output to the standard error output and logs, and the processing will end (KDJW71022-E).
  • Specify single-byte alphanumeric characters for the namespace URI. If you specify other than the single-byte alphanumeric characters, the operations are not guaranteed.
Protocol
  • Only a domain name beginning with http:// or urn: is valid as the namespace URI to be coded in the -portname option. The namespace URIs beginning with https:// and file:// are handled as invalid. If you specify a namespace beginning with other than http:// or urn:, an error message will output to the standard error output and logs, and the processing will end (KDJW71018-E).
  • You cannot specify a relative path for the namespace URI to be coded in the -portname option. If you specify a relative path for the namespace URI, an error message will output to the standard error output and logs, and the processing will end (KDJW71019-E).
Information that you cannot specify
You cannot code query strings, anchors, port numbers, user names, and passwords in the namespace URI to be coded in the -portname option. If you specify this information in the namespace URI, an error message will output to the standard error output and logs, and the processing will end (KDJW71020-E).
Character strings that you can code
In a segment demarcated with delimiters such as a forward slash (/) or a period (.), you can code a character string that satisfies all the conditions described in the following table:

Table 14-8 Conditions for character strings that you can code in a namespace (When specifying the -portname option)

No. Condition Examples of invalid character strings Operation when an invalid character string is specified
1 Character strings using only single-byte alphanumeric characters (0 to 9, A to Z, and a to z) http://hitachi.com/
http://133.145.224.19/
http://[1080:2C14;D30:BA04:275:806:270C:418A]/		 The operation is not guaranteed (no error message is displayed).
2 Character strings containing other than reserved terminology of Java http://hitachi.com/abstract The operation is not guaranteed.
3 Character strings that do not begin with a numeric character http://1hitachi.com
Port name
  • If you omit the port name, an error message will output to the standard error output and logs, and the processing will end (KDJW71021-E).
  • Specify single-byte alphanumeric characters and underscores for the port name. If you specify other than the single-byte alphanumeric characters and underscores, the operations are not guaranteed.

Notes for specifying -soap12binding
You can specify only "DEFAULT" or "WSI_BP20_TRANSPORT" for the -soap12binding option. If you specify any other value, an error message will be output to the standard error output and logs, while Help will be output to the standard output, and the processing will end (KDJW71030-E).
The following table describes the relationship between the -soap12binding option and the transport attribute value of the soap12:binding element of WSDL generated by the cjwsgen command.

Table 14-9 Relationship between the -soap12binding option and transport attribute value

No. Option specification Option specified value Set value of the transport attribute
1 Not specified None http://www.w3.org/2003/05/soap/bindings/HTTP/
2 Specified DEFAULT
3 WSI_BP20_TRANSPORT http://schemas.xmlsoap.org/soap/http

Notes for specifying the -classpath and -cp options
The following are the notes related to the specified values of the -classpath option and the -cp option:
  • If you omit the options, the environment variable CLASSPATH is used as the class path. If you specify the options, the environment variable CLASSPATH is ignored.
  • The value you specify in the environment variable CLASSPATH is used as it is, and therefore, even if the value includes a blank space, you need not enclose the value within double quotation marks (""). If you specify a value in such a format, in which the value is enclosed within double quotation marks (""), the operations are not guaranteed.
  • If you omit the options and also do not specify the environment variable CLASSPATH, the current directory will be used as the class path.
  • You can specify either a relative path or an absolute path for the class path.
  • You can also specify a JAR file as the class path.
  • When specifying more than one class path, code a semicolon (;) between two class paths.
  • Do not use the following characters in the class path to be specified. If you use the characters, the operations are not guaranteed.
    # % & ^
  • If the specified class path is invalid, an error message will output to the standard error output and logs, and the processing will end (KDJW71026-E).

Combination of the -d, -s, and -keep options and the output destination directory and the work directory
If the -d option is specified, the already compiled class file (*.class) will output to the directory specified in the -d option, and if the -d option is not specified, the already compiled class file (*.class) will output in the current directory.
The following table describes the combination of options and provides the information about whether to output source file (.java) or if the source file is output, the output destination directory, and the work directory used by the cjwsgen command. Note that if you want to use only the resource file, it is all right if the source file is not output.

Table 14-10 Availability of the source file output and the output destination directory

Whether the option is specified Whether to output the source file
The output destination directory and work directory
-d -s -keep
Y Y Y The directory specified by the -s option is used as the work directory and the source file is output.
Y Y N
Y N Y The directory specified by the -d option is used as the work directory and the source file is output.
Y N N The directory specified by the -d option is used as the work directory. The source file is not output.
N Y Y The directory specified by the -s option is used as the work directory and the source file is output.
N Y N
N N Y The current directory is used as the work directory and the source file is output.
N N N The current directory is used as the work directory. The source file is not output.

Legends:
Y: Indicates that the option is specified.
N: Indicates that the option is not specified.

Combinations and output destination directory of the -d, -r, -soap, -servicename, -portname, -soap12binding, and -wsdl options
The following table describes the combination of options and provides the information about whether to output resource files (*.wsdl and *.xsd)) or if the resource files are output, the location of the output destination directory:

Table 14-11 Availability of resource file output and the output destination directory

Availability of option and specification Output or not Output destination
-d option -r option -soap, -servicename, -portname, and -soap12binding option -wsdl option
Specified Specified Specified Specified Y Directory specified in the -r option
Not specified
Not specified Specified
Not specified
Not specified Specified Specified Y Directory specified in the -d option
Not specified
Not specified Specified Y Directory specified in the -d option
Not specified N --
Not specified Specified Specified Specified Y Directory specified in the -r option
Not specified
Not specified Specified
Not specified
Not specified Specified Specified Y Current directory
Not specified
Not specified Specified Y Current directory
Not specified N --

Legend:
--: Not applicable because the resource files are not output.
Y: Indicates that the resource files are output.
N: Indicates that the resource files are not output.

(3) Generated files

The following table lists and describes the files generated when you execute the cjwsgen command:

Table 14-12 List of files generated when executing the cjwsgen command

No. Generated file Contents
1 Request bean class This is the JavaBeans class for the request message. This file is output when the generated Service Implementation Class has the wrapper format.
2 Response bean class This is the JavaBeans class for the response message. This file is output when the generated Service Implementation Class has the wrapper format.
3 Fault bean class This is the JavaBeans class corresponding to the fault. This file is output when the wrapper exception class is specified in the Java code that you have specified, and the fault bean does not exist.
4 WSDL This is a WSDL file.
5 XSD This is an XML schema definition file.

Creating a directory for file generation
If you execute the cjwsgen command, a directory corresponding to the package name of the generated files is created in the specified output destination directory, and files are output to this directory.
The following are the specification example and the output destination:
  • Command specification example
    cjwsgen -d ./output -s ./output -keep -cp . com.example.UserInfoImpl
  • Output destination
    If a JavaBean class exists in the class file of the Service Implementation Class specified in the cjwsgen command, the source file and the already compiled class file of the JavaBean class are output to the following jaxws sub package (except in cases where the package name is customized using annotations):
    ./output/com/example/jaxws/
Also, the files generated under the resource file are output to the directory specified in the argument of the cjwsgen command. The following are the specification example and the output destination:
  • Command specification example
    cjwsgen -r ./output -cp . com.example.UserInfoImpl
  • Output destination
    ./output/

Notes for file generation
If a file with the same name exists in the output destination directory of the generated file, the file is overwritten.

Output of header information of Javadoc
In the generated file, the Cosminexus-related information is output in the header information as Javadoc.

(4) Relationship between the Input Service Implementation Class and output resource files

The following table describes the relationship between the Input Service Implementation Classes and output resource files:

Table 14-13 Relationship between the Input Service Implementation Class and output resource files

Input Service Implementation Class Output resource
WSDL XSD
Number of files File name Number of files#1 File name
Without SEI 1 name attribute value of the wsdl:service element 1 to N#2 name attribute value of the wsdl:service element + suffix (_schemaN)#2
With SEI (same namespace as the Service Implementation Class) 1 name attribute value of the wsdl:service element 1 to N#2 name attribute value of the wsdl:service element + suffix (_schemaN)#2
With SEI (different namespace from the Service Implementation Class) 2
  • For an abstract WSDL file#3
    name attribute value of the wsdl:portType element
  • For an implementation WSDL file#4
    name attribute value of the wsdl:service element
 1 to N#2 name attribute value of the wsdl:portType element + suffix (_schemaN)#2

#1
The file is generated, if the namespace of the schema is different.

#2
N is the number of namespaces of the schema. The upper-limit count of files that you can generate depends on the OS.

#3
Abstract WSDL indicates WSDL of 'wsdl:types element, wsdl:message element, and wsdl:portType element'.

#4
Implementation WSDL indicates WSDL of 'wsdl:binding element and wsdl:service element'.

(5) Operation during processing

If you execute the cjwsgen command, a message (KDJW70001-I) indicating the command execution will output to the standard output and log, and processes such as the generation and deletion of JavaBeans, and generation of WSDL and XSD will be executed. The following is the description about each process:

Process for generating JavaBeans
When the generation of JavaBeans starts, a message indicating the start of the generation process will output to the standard output and the log (KDJW70004-I). If an attempt to generate JavaBeans fails, an error message indicating the cause of the error will output to the standard error output and the log (KDJW70005-E).

Process for generating WSDL and XSD
When the generation of the resource files (WSDL and XSD) corresponding to the contents of the generated JavaBeans starts, a message indicating the start of the generation process will output to the standard output and log (KDJW70006-I). If an attempt to generate the resource files fails, an error message reporting the cause of the error will output to the standard error output and log (KDJW70007-E).

Process for deleting JavaBeans
Delete the source file of the generated JavaBeans. However, in some cases, the source file might not be deleted depending on the specification contents of the options. For details about the options, see the section 14.3(2) List of options.

(6) End codes

The following are the end codes of the cjwsgen command:

0: Normal termination
Unless an error that cannot be allowed to continue during the processing is detected, a message indicating the termination with standard output and logs will be displayed, and the processing will end (KDJW70002-I).

1: Abnormal termination
  • If a minor error that allows the continuation of the process is detected midway, a warning message will output, and the processing will continue.
  • If an error that does not allow the continuation of the process is detected midway, a message indicating termination will be output to the standard output and log, and the processing will end (KDJW70003-E). For details about the action to be taken for the abnormal termination, see 14.3(7) Action for abnormal termination.
  • If multiple errors are detected, the error detected first will be displayed, and a message indicating termination will output to the standard output and log, and the processing will end.
  • If you execute the cjwsgen command, the apt command is invoked. Therefore, error messages of the apt command might be output.
  • The directories and files generated prior to the detection of the error are not deleted and are retained, even when the command terminates abnormally.

Note that depending on the output level (importance) that you have set, the log might not be output. For details on the settings of the output level of a log, see 10.1.2 Settings for the common definition file.

(7) Action for abnormal termination

If the cjwsgen command terminates abnormally during the execution, an error message will output and the processing will end. In such cases, remove the cause of the error that is output and re-execute the cjwsgen command.

Even when multiple errors occur, the error that is detected first will be displayed. In such cases, repeatedly execute the cjwsgen command and remove the causes of the displayed error one by one.

Note that if the command terminates abnormally due to inaccuracy of the class file of the Service Implementation Class, you need to modify the Java sources that are the generated source of the class file, and then revise the compilation.

[Contents][Back][Next]

[Trademarks]

All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.