| Agile Product Lifecycle Management AIS Developer Guide Release 9.3.3 E39309-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management AIS Developer Guide Release 9.3.3 E39309-02 |
|
Previous |
Next |
This chapter includes:
Tools that you can use to develop client applications
Languages that can generate and process XML and process HTTP request/response messages
General steps to access the prebuilt AIS Web Services (The examples in the AIS_sample folder illustrate these steps.)
There is no single tool set to access Web Services. Tools that you choose are a function of the environment that you use to develop your clients. Essentially, you need tools to enable generating and processing XML files and HTTP request/response messages.
Although AIS is based on Axis, which is a SOAP processor, you can use other implementations of SOAP tools regardless of the source language to build Web service clients.
Oracle recommends, tests, and certifies Java to develop AIS clients.
WSDL is only supported with J2EE.
This is a list of some of the Web sites where you can find more information about these development tools:
Apache Axis -- Open source SOAP implementation for Java. See the following Web site: http://ws.apache.org/axis/
GlassFish Application Server -- GlassFish is a complete Java EE 5 Application Server. See Java Web Services Developer Pack at http://glassfish.java.net/public/downloadsindex.html.
Microsoft .Net -- An XML Web Services platform for Microsoft Windows that can be used to create Web service clients. See the following Web site for more information: http://msdn.microsoft.com/en-us/netframework/
AIS was only tested with Java. Other tools and environments such as VB .Net should work, but AIS was not tested and is not supported for these tools and environments (operability with .Net (Visual C#) was tested with an earlier version of AIS).
SOAP::Lite for Perl -- A Perl implementation of the SOAP protocol. See the following Web site: http://www.soaplite.com/
In general, to access AIS Web Services, you need to:
Generate a SOAP request -- In many cases, a Web-Service-aware code library will be able to generate client-side stubs that generate an appropriately formatted SOAP request.
Submit that request to AIS via HTTP or HTTPS -- Once an appropriate set of client-side Java stubs are generated, a client application can use these stubs to submit a request.
Process the SOAP response -- The client-side stubs usually are responsible for processing the SOAP response and converting the response into an appropriate set of return objects.
The AIS samples provide comprehensive examples of how SOAP and Web service-related libraries can make this process simple. The following sections illustrate using the ExportData sample in "Running the Java Samples" and the above steps in greater detail.
Before compiling and running the AIS Web service client samples, make sure the clients are functioning properly on the Agile PLM Application Server. For more information, refer to the Agile PLM Installation Guide.
AIS provide several Java Web service client samples for you to download. These samples use Axis to connect with the AIS Web service engine to generate client-side stubs. You can use these sample clients to export and import data. They provide command-line interfaces to the ExportData, ExportPartlist, and ImportData Web service operations.
These AIS Java samples do not expose all AIS functionalities. They are only sample clients. For example, they enable running only one query at a time, while AIS supports runing multiple queries and then aggregating the results. You may choose to develop AIS clients with additional functionality. The samples provide source code that you can use to practice developing your own AIS clients. For more information about functionalities supported by the Export and Import Web Services, refer to the Export and Import XML Schema documentation in Agile PLM's Import/Export User Guide.
Before building and running the AIS samples, download the following required tools:
Java 2 SDK SE Version 1.5. You can download this software at: http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-javase5-419410.html
The Apache Project's Ant build tool, version 1.6, available at: http://ant.apache.org/
This section provides instructions to install the Java SDK on Windows and on Solaris platforms. You can skip this section if you already have the proper version of Java installed.
To install the Java SDK on Windows:
Double-click the distribution and follow the installation procedures.
Set the system variable JAVA_HOME to point to the home directory of your Java SDK installation (for example, D:\j2sdk150).
To install the Java SDK on Solaris:
Execute the distribution (for example, $ ./ j2sdk-1_5_0-solaris-sparc.sh) and follow the installation procedures.
Set the environment variable JAVA_HOME to point to the home directory of your Java SDK installation (for example, /home/<user>/j2sdk150).
Execute your.profile.cshrc or (depending on your shell) file to set up your environment.
This section provides the instructions for installing Ant on Windows and on Solaris.
To install Ant on Windows:
Extract the contents of the ZIP archive to a local directory and follow the installation procedures.
The Ant distribution for Windows is a ZIP file (for example, apache-ant-1.6.0-bin.zip).
Open a command prompt window and verify that Ant can be invoked by entering the following command: %ANT_HOME%\bin\ant -version
The following output should be displayed: Apache Ant version 1.6.0 compiled on <date>
To install the Ant on Solaris:
Extract the contents of the tar archive to a local directory (for example, /home/user/ant) and follow the procedures.
The ANT distribution for UNIX is a tar file (for example, apache-ant-1.6.0-bin.tar.gz).
Execute your .profile or .cshrc (depending on your shell) file to set up your environment.
From a command prompt, verify that Ant can be invoked by entering the following command: $ANT_HOME/bin/ant -version
Upon successful installation, the following message appears:
Apache Ant version 1.6.0 compiled on <date>.
Building the Java samples is straightforward. You need the Ant build tool, which is available for download at: http://ant.apache.org/. For procedures, see "Installing Ant." Run Ant within the samples directory, pointing the URL to your AIS installation.
If you generated client stubs for the AIS samples from the WSDL, they will run on any other computer. Alternately, if you have the WSDL, you can use it to generate the client stubs on another computer.
To build the AIS Java samples on Windows:
Download wsdl4j-1.5.1.jar from http://archive.apache.org/dist/ws/axis/1_2/.
Copy the contents to the ais/lib folder and rename it to wsdl4j.jar.
Open a command prompt window and navigate to the AIS samples folder, which contains the file build.xml.
Type the following command:
%ANT_HOME%\bin\ant -Dais.url=https://<hostname:port/virtualPath>/ws -Dusername= <username> -Dpassword= <password target>
Where:
hostname - This is name of the Agile server.
port - This is the application server port. If you are using an Oracle Application Server to host the Agile PLM system, type 7777. If you are using WebLogic Server, type 7001
target - This identifies the AIS sample to build. Available build targets are export, import, and all. The default target is all. If you do not specify a target, all AIS samples will be built.
username - This is the Agile PLM user name
password - This is the Agile PLM password
After you build the samples, use the runner file in the AIS samples directory to run the samples. It contains all the necessary CLASSPATH initializations for the samples
|
Note: Agile PLM requires bothusername and password to build the Java samples. The makefile execution will fail if the three parameters are not set. |
To build the AIS Java samples on Solaris:
Navigate to the AIS samples directory and locate the file build.xml and then type the following command:
$ANT_HOME/bin/ant -Dais.url=http://<hostname:port/virtualPath/ws target>
After you build a sample, use the runner file in the AIS samples directory to run the sample. This file contains all the necessary CLASSPATH initializations for the samples. For more information, refer to the comments (in Javadoc) for each sample.
If you are connecting to a secure URL that uses SSL, type the following command instead. For descriptions of hostname, port, virtualPath, username, password, and target, see the previous section
$$ANT_HOME/bin/ant -Dais.url=http://<hostname:port/virtualPath>/ws -Dusername=<username> -Dpassword=<password target>
To build Java AIS samples on servers with Secure Sockets Layer (SSL) enabled:
Get the self-signed certificate from the server.
Install the self-signed certificate into your Java development environment.
Build the sample programs as described above by connecting to the server using HTTPS.
Run the sample programs as usual but include the command line parameter -P. For example:
runner importer.ImportData -P HTTPS <insert other parameters here>
The Readme.txt file that is installed with the AIS samples includes more information about obtaining a certificate, installing it in your Java environment, and building and running the AIS samples on an SSL-enabled system.
After you build the samples, use the runner file in the AIS samples directory to run the samples. This file contains the necessary CLASSPATH initializations for the samples.
Depending on your operating environment (Windows or Solaris), once you perform the build, one of the following files will appear in the AIS samples directory:
On Windows, the file is runner.bat
On Solaris, the file is runner.sh
These files contain the necessary CLASSPATH initializations and you can use them to simplify the process of invoking a sample application.
The invocations below will print out usage statements for each of the examples. You can use these usage statements along with the additional documentation provided on the samples to determine how to run the samples in a meaningful fashion.
To print out usage statements for the clients, type the following commands:
> runner export.ExportData > runner export.ExportPartlist > runner importer.ImportData > runner importer.ImportSupplierResponse > runner importer.ValidateData
Usage: export.ExportData <options>
| Option | Description |
|---|---|
| -a axml | This selects the aXML output format instead of the default PDX output format. |
| -c criteria | This is the search criteria for locating objects to export. The criteria must be formatted using the Agile SDK query language. For more information, refer to Agile PLM SDK Developer Guide. |
| -e virtual-path | This is the Agile PLM virtual path. For example, if you access Agile Web Client via http://www.sample.com/Agile/PLMServlet, the virtual path is "Agile". When you install the Agile PLM system, the default virtual path is "Agile". |
| -f filter | This is the predefined filter name or ID. If you have administrator privileges, you can define Agile PLM filters using the Agile Java Client. |
| -F filter-flag | This is the ad hoc filter flag. The legal values for this argument derive from the <filters> element shown in the Export XML Schema documentation. The filter flags correspond to child elements with names ending in "Filter," like ChangeFilter and ItemFilter. The basic pattern for this option is filter-name.attribute.value where:
filter-name corresponds to the name of the XML element, such as attribute corresponds to the name of the attribute that is defined (for example, "PageTwo"). value corresponds to the value for the attribute. If the attribute is a boolean, the value is optional and defaults to "true." For the Attachments attribute, the value "Tables and Files" causes the attachment table and all the referenced files to be exported. Following is an example of a filter flag: -F "Item.TitleBlock" "Item.Attachments.TableAndFiles" "Item.BOM.Recurse" If you are extracting data to PDX files, the filter flag should be a superclass filter such as runner export.ExportData -h agilesvr -l 7001 -u aisuser -p agile -t ECO -c "[Number] is not null" -F "ChangeFilter.CoverPage" -o eco.pdx In aXML files, the filter flag must be a class filter such as runner export.ExportData -h agilesvr -l 7001 -u aisuser -p agile -t ECO -c "[Number] is not null" -F "ECOFilter.CoverPage" -o eco.axml -a axml For a complete list of filter types, refer to the Export XML Schema Documentation in Agile PLM's Import/Export User Guide. |
| -h host | This is the Agile PLM server machine. The default is localhost. |
| -l port | This is the port on which the Agile PLM server is listening. The default is 80. |
| -o output-file | This is the output file name. It defaults to: either out.pdx or out.axml, depending on the output format. |
| -p password | This is the user's password. |
| -P protocol | This is the URL protocol. Valid values are either HTTP (the default) or HTTPS. |
| -s site | This is the manufacturing site for which data is extracted. If you do not specify a manufacturing site, data is extracted for all sites. |
| -t type | This is the type of the required object. Type either the class name or the predefined object type Default:Items. For a list of predefined object types, refer to Export XML schema documentation in Agile PLM's Import/Export User Guide.
This is the Export XML schema, export.xsd. You can find this file in the samples folder described in "AIS Folders." |
|
? |
The pre-defined types listed in export.xsd maps to Agile PLM classes, not subclasses. For example, the predefined ECO object type actually maps to the Change Orders class, not the ECO subclass. If you specify -t ECO when you run ExportData, objects of the Change Orders class will be exported, not objects of the ECO subclass.
If you want to use only your Agile PLM system's class names and subclass names for object types instead of the predefined Export object types, you can modify the ExportData.java source code and disable pre-defined object types by replacing the following lines of code:
try {
// Let's try to use a predefined type.
objType.setPredefined(ObjectTypes.fromString(type));
} catch (Exception ex) {
// Fall back to specifying a type by name (i.e., user-defined type)
objType.setTypeName(type);
}
with this line: objType.setTypeName(type); |
| -T timeout | This is the time in minutes to wait for a response. The defaults to 15 minutes. |
| -u user | This is the Agile PLM username. |
The export.ExportData client does not have an option to specify an item's revision. When you use the client to export items, the latest released revision is exported. However, you can develop an AIS client that lets you specify a revision to export. For more information, refer to the Export XML Schema documentation in Agile PLM's Import/Export User Guide.
These examples show how to run the export.ExportData client.
runner export.ExportData -h agilesvr -u aisuser -p e-agile -l 7001 -c "[Title Block.Number] equal to 'P00014'" -t Part -F "Item.TitleBlock" "Item.PageTwo" "Item.Attachments.TableAndFiles" "Item.BOM.Recurse" -o P00014.pdx
runner export.ExportData -h agilesvr -u aisuser -p agile -l 7001 -c "[Title Block.Number] equal to '1000-02'" -f "Default Item Filter" -t Item -s "San Jose" -o D:\data\out.pdx
runner export.ExportData -h agilesvr -u aisuser -p e-agile -l 7001 -c "[Title Block.Number] equal to '1000-02'" -f "Default Item Filter" -t Item -a axml
runner export.ExportData -h agilesvr -u aisuser -p e-agile -l 7001 -c "[General Info.Name] equal to 'ACT'" -f "Default Manufacturer Filter" -t Manufacturer
Substitute appropriate port numbers. For example, for Weblogic use port 7001, and for OAS use port 7777. For readability, these examples use attribute name, such as [Title Block.Number], instead of IDs. Agile strongly recommends using attribute IDs. If you use attribute names, make sure they are fully qualified to avoid ambiguity.
Usage: export.ExportPartlist <options>
| Option | Description |
|---|---|
| -c criteria | This is the search criteria to locate objects you want to export. The ExportPartlist command exports data only for items with AMLs (approved manufacturer parts and their associated manufacturers). The criteria you specify must be formatted using the Agile SDK query language. For more information, refer to Agile SDK Developer Guide. |
| -e virtual-path | This is the Agile PLM virtual path. For example, if you access Agile Web Client via http://www.sample.com/Agile/PLMServlet, the virtual path is "Agile". When you install the Agile PLM system, the default virtual path is "Agile". |
| -f filter | This is the predefined filter name or ID. If you have administrator privileges, you can define Agile PLM filters using the Agile Java Client. |
| -F filter-flag | This is the ad hoc filter flag. The valid values for this argument derive from the <filters> element shown in the Export XML Schema documentation in Agile PLM's Import/Export User Guide. The filter flags correspond to child elements with names ending in "Filter," such as ChangeFilter and ItemFilter. The basic pattern for this option is filter-name.attribute.value. filter-name corresponds to the name of the XML element, such as ItemFilter (the "Filter" suffix may be omitted). attribute corresponds to name of the attribute being defined (for example, "PageTwo"). value corresponds to the value for the attribute. If the attribute is a boolean, the value is optional and defaults to "True." For the Attachments attribute, the value "Tables and Files" causes the attachment table and all the referenced files to be exported.
The filter flag should be a class filter such as This is an example of a filter flag:
|
| -h host | This is the Agile PLM server machine. The default is localhost. |
| -l port | This is the port on which the Agile PLM server is listening. The default is 80. |
| -o output-file | This is the output file name. The default is out.axml, or out.pdx. |
| -p password | This is the user's password. |
| -P protocol | This is the URL protocol. Valid values are either HTTP (the default) or HTTPS. |
| -r revision | This is the item revision to export. |
| -s site | This is the manufacturing site for which data is extracted. If you do not specify a manufacturing site, data is extracted for all sites. |
| -T timeout | This is the time to wait for a response (in minutes). It defaults to15 minutes. |
| -u user | This is the Agile PLM username. |
These examples show how to run the export.ExportPartlist client.
runner export.ExportPartlist -h agilesvr -u aisuser -p agile -l 7778 -c "[Title Block.Number] equal to 'P00408'" -f "Default Item Filter" -o D:\out.axml
runner export.ExportPartlist -h agilesvr -u aisuser -p agile -l 7001 -c "[Title Block.Number] equal to 'P00502'" -r "A" -f "Default Item Filter" -o D:\data\out.axml
runner export.ExportPartlist -h agilesvr -u aisuser -p agile -l 7778 -c "[Title Block.Number] equal to 'P00025'" -f "Default Item Filter" -o D:\data\partlist_rev.axml -r "A"
runner export.ExportPartlist -h agilesvr -u aisuser -p agile -l 7778 -c "[Title Block.Number] equal to 'P00163'" -f "Default Item Filter" "Default Manufacturer Filter" "Default Manufacturer Part Filter" -o D:\data\partlist_bom.axml -r "B"
Usage: importer.ImportData <options>
| Option | Description |
|---|---|
| -a mapfile | This is a previously saved mapping definition file. |
| -e virtual-path | This is the Agile PLM virtual path. For example, if you access Agile Web Client via http://www.sample.com/Agile/PLMServlet, the virtual path is "Agile". When you install the Agile PLM system, the default virtual path is "Agile". |
| -f filetype | This is the type of file that is imported. If this option is omitted, the client determines the filetype based on the MIME type of the import source file. |
| -h host | This is the Agile PLM server machine. The default is localhost. |
| -i input-file | This is the source data file. |
| -l port | This is the port on which the Agile PLM server is listening. The default is 80. |
| -m map | A textual mapping definition. Arguments should take the form of <source-path>=<target-path>. |
| -n option | This is the an import server option. Arguments take the form of <group>|<option>=<value>. Please see the Import XML Schema documentation for more information on available options. |
| -o output-file | This is the output file name. The default is log.xml. |
| -p password | This is the user's password. |
| -P protocol | This is the URL protocol. Valid values are either HTTP (the default) or HTTPS. |
| -t type | This is the type of import operation(s) to run. At least one type must be specified. The format of a type argument is type[.<child-type>] (for example., items.bom, manufacturerParts.attachments, and prices.priceLines). Please see the Import XML Schema documentation for a complete set of available import types. |
| -T timeout | This is the time to wait for a response (in minutes). It defaults to 15 minutes. |
| -u user | This is the Agile PLM username. |
| -x transform | This is the a previously saved transformation definition file. For information on how to use the Import wizard to create a transformation definition file, refer to Agile PLM Import and Export Guide. |
These examples show how to run the importer.ImportData client.
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\data\bom2.txt -f DelimitedTextFile -t items -n "BusinessRuleOptions|ChangeMode=Authoring" "TextParser|FieldDelimiter=," -o D:\data\result.xml -m Parent="Part.Title Block.Number" Child="Part.Title Block.Description"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\data\bom2.txt -f DelimitedTextFile -t items -n "BusinessRuleOptions|ChangeMode=Authoring" "TextParser|FieldDelimiter=," -o D:\data\result.xml -m Parent="Part.Title Block.Number" Child="Part.Title Block.Description" Type="Part.Title Block.Part Type"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\data\Book1.xls -f ExcelFile -t items -m num="Part.Title Block.Number" desc="Part.Title Block.Description" type="Part.Title Block.Part Type" -o D:\data\result.xml -n "ExcelFileParser|SelectWorksheet=1"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\Item\item_tab.txt -a D:\SourceFiles\Mapping\Item\item_tab.xml -t items -f DelimitedTextFile -o D:\SourceFiles\Baseline\Item\item_tab_import.xml -n "BusinessRuleOptions|ChangeMode=Authoring" "TextParser|FieldDelimiter=tab"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\price_lines_import.xls -a D:\SourceFiles\Mapping\price_lines_import.xml -f ExcelFile -t prices.priceLines -o D:\SourceFiles\Baseline\price_lines_import.xml -n "BusinessRuleOptions|ChangeMode=Redline" "BusinessRuleOptions|ChangeNumber=PCO00005"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\AML_PC.txt -a D:\SourceFiles\Mapping\AML_PC.xml -t items.aml items.bom -f DelimitedTextFile -o D:\SourceFiles\Baseline\AML_PC.xml -n "BusinessRuleOptions|ChangeMode=Redline" "BusinessRuleOptions|ChangeNumber=C00041" "Template|TemplateType=com.agile.imp.template.TemplateParentChildFilter"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\bom_RefDelimiter.txt -a D:\SourceFiles\Mapping\bom_RefDelimiter.xml -t items.bom -f DelimitedTextFile -o D:\SourceFiles\Baseline\new_bom.xml -n "BusinessRuleOptions|ChangeMode=Authoring" "BusinessRuleOptions|ReferenceDesignatorRangeCharacter=-" "BusinessRuleOptions|ReferenceDesignatorDelimiterCharacter=,"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\bom_Level.txt -a D:\SourceFiles\Mapping\bom_Level.xml -t items.bom items.aml -f DelimitedTextFile -o D:\SourceFiles\Baseline\bom_Level.xml -n "BusinessRuleOptions|ChangeMode=Redline" "Template|TemplateType=com.agile.imp.template.TemplateLevelFilter" "BusinessRuleOptions|ChangeNumber=C00013"
runner importer.ImportData -h agilesvr -u aisuser -p agile -l 7778 -i D:\SourceFiles\Source\Item\item_comma_category.txt -a D:\SourceFiles\Mapping\Item\all_mapping_comma.xml -o D:\SourceFiles\Baseline\all_mapping_comma.xml -t items -f DelimitedTextFile -n "BusinessRuleOptions|ChangeMode=Authoring" "TextParser|FieldDelimiter=," "TextParser|LocationOfHeaderRow=3" "TextParser|FileEncoding=ISO8859_1" "ParsingAndValidationOptions|MultilistDelimiterCharacter=;" "ParsingAndValidationOptions|WhitespaceValidationAction=Reject" "ParsingAndValidationOptions|CaseValidationAction=Convert" "ParsingAndValidationOptions|LengthValidationAction=Reject" "TextParser|TextQualifier='"
Usage: importer.ImportSupplierResponse <options>
| Option | Description |
|---|---|
| -e virtual-path | This is the Agile virtual path. For example, if you access Agile Web Client via http://www.sample.com/Agile/PLMServlet, the virtual path is "Agile". When you install the Agile PLM system, the default virtual path is "Agile". |
| -h host | This is the Agile server machine. The default is localhost. |
| -i input-file | This is the source data file. |
| -l port | This is the port on which the Agile server is listening. The default is 80. |
| -o output-file | This is the output file name. The default is log.xml. |
| -p password | This is the user's password. |
| -P protocol | This is the URL protocol. Valid values are either HTTP (the default) or HTTPS. |
| -r RFQ-number | This is the RFQ into which you are importing the supplier's response. |
| -s supplier-number | This is the supplier number. It is needed only when a buyer imports an RFQ response for an off-line supplier. If the supplier number is not specified, the import server retrieves the supplier number from the specified input file. |
| -T timeout | This is the time to wait for a response (in minutes). It defaults to 15 minutes. |
| -u user | This is the Agile username. |
These examples show running the importer.ImportSupplierResponse client.
runner importer.ImportSupplierResponse -h agilesvr -u joesupplier -p agile -l 7778 -i D:\SourceFiles\Source\RFQ00256.csv -r RFQ00256
runner importer.ImportSupplierResponse -h agilesvr -u joebuyer -p agile -l 7778 -i D:\SourceFiles\Source\RFQ00013.csv -o D:\SourceFiles\Source\Response.xml
Usage: importer.ValidateData <options>
The options are exactly the same as the importer.ImportData Web service. See the command "importer.ImportData Usage."
Using the ExportData sample, this section provides the procedures to create a Web service client application for AIS.
You can generate an appropriate SOAP request using client-side stubs. You can also generate client-side stubs. The Web-Service-aware code libraries are able to generate client-side stubs on your behalf. This entails using a code generation utility along with the WSDL for the desired Web service.
AIS provided samples that make use of Axis in order to connect with the AIS Web service engine. Axis provides a WSDL2Java utility that you can use for this purpose; other Web-Service-aware libraries will have their own client-side stub generation facility (for example, .Net includes a wsdl.exe utility). In the case of the samples, the client-side stub generation occurs during the samples' build process. Within the build.xml file is the following Ant target:
<target name="generate-export-stubs" depends="init"unless="exp-stubs.present"><echo>Generating export Java client-side stubs fromWSDL...</echo><java fork="true"classname="org.apache.axis.wsdl.WSDL2Java"failonerror="true"><classpath refid="build.classpath"/><arg line="-o ${built.scratch.dir}/gen"/><arg line="-p export"/><arg line="${ais.url}/Export?wsdl"/></java></target>
Axis also includes an Ant task definition which you can use instead of the above <java> task. For more information, visit the Axis Ant Tasks site by pasting this URL in your browser http://ws.apache.org/axis/java/ant/ant.htmlhttp://ws.apache.org/axis/java/ant/ant.html.
The above Ant target is responsible for generating the export-related client-side stubs. This invocation retrieves the Export WSDL from ${ais.url}/Export?wsdl, generates Java code in the export Java package, and places the source code within the ${built.scratch.dir}/gen directory. For more information on the WSDL2Java utility, refer to Axis documentation on the Axis Website at http://ws.apache.org/axis/.
Once the client-side stubs have been generated, the user can use the generated object definitions in order to more easily generate the appropriate SOAP request. These stubs enable the user to focus on the capabilities of the target Web service operation without the need to construct a valid SOAP request. In the ExportData.java sample, you can see that the run method contains all the code used to generate the SOAP request. However, instead of explicitly constructing a SOAP request, the code is concerned with setting up a Java data structure, which will be provided as the parameter to a stub method invocation. The code is more concerned with functionality than formatting, which makes it easier to read, write, and maintain.
The sample.zip folder contains the source code of an Import/Export Web service client. If you use this client, there is no need to modify the code for the client to connect to Axis v1.4. However if you plan to use an in-house, or a third party client, you must modify the code and work with Axis v1.4.
The next step in the Web service operation is to properly submit the generated SOAP request to the Web service engine. When dealing with generated client-side stubs, this step only requires pointing the stubs to the desired server and invoking a method on the stubs. You do not need to worry about opening a connection or manually marshaling your data onto the wire (Marshaling is the act of taking data from the environment you are in and exporting it to another environment), because the generated stubs will handle these details.
The ExportData.java sample illustrates the above statement in two places:
The getExportStub method is responsible for pointing the client-side stubs to the desired Web service engine.
The stub.exportData method invocation found within the run method is responsible for actually submitting the request to the Web service engine. The actual submitting of the request and all the minutiae that entails are managed by the stubs themselves; you do not need to worry about the connecting, submitting, or marshaling particulars.
The details on how you point the stubs to the desired Web service engine and submit the request will vary from code library to code library. For more information, refer to the documentation for your Web-Service-aware code library. XXX
Similar to submitting a SOAP request, processing a SOAP response is handled with the generated client-side stubs. Without these generated stubs, you must parse the XML-based SOAP response and resolve the many formatting and unmarshaling issues that arise. However, when working with generated stubs, all these details are taken care of so that you will receive the Java objects in a proper form.
The ExportData.java sample illustrates this point clearly. In this sample, you can see that the result of the stub.exportData method is a javax.activation.DataHandler, which is a convenient way of encapsulating a binary data stream. Rather than requiring you to parse an XML document and interpret the returned data, the stubs automatically do this and return the response's attachment as a DataHandler object.
The details on how SOAP responses are processed vary from code library to code library. For more information, consult the documentation for your Web-Service-aware code library.
|
 Copyright © 2010, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|