Setting Web services preferences

Setting Web services preferences

To set any of the Web services preferences,...
Click Window > Preferences to open the Preferences notebook.
Expand Web services, and click the preference category that you want to set
Select the check boxes that you want to set as the default when creating your Web service.
Click OK to apply the changes and close the Preferences notebook.
If you require more information on any of the options, select the option and press F1.
Web services tools enable you to define the following preferences:

Backward Compatibility

The Backward Compatibility preference enables you to use options that are compatible with previous WebSphere Studio releases. This preference only applies if you are using Web services that use the IBM SOAP run-time environment.
If you have underscores or other characters not allowable as Java identifiers in:
names for bean attribute when creating web services from Java bean or EJB
element names in complex types in XSD files when creating web service client proxy
do not select the Use V4 mapping style Web Services backward compatibility preference. For example, if you have a bean called Bean with attribute called mybean_name and specify Use V4 mapping style, you may run into an error similar to the following at run time: exception: [SOAPException: faultCode=SOAP-ENV:Client; msg=Unable to unmarshall mappings.BeanContentType. Unable to find setter method with method name setMybeanName for class mappings.BeanContentType.]

Code Generation

The Code Generation preferences enable you to set the following options:
If you are creating Web services with the IBM SOAP run-time environment:
Use absolute location URI for WSDL import statements.
Use inline schema when generating code.
Enable element-based mappings to proxy files.
Map XML simple data types to java.lang wrapper classes instead of to Java primitive types.

If you are creating Web services with the IBM WebSphere run-time environment:
Disable data binding and use SOAP elements when generating Java from WSDL. By default, the Web services wizards follow JAX-RPC rules and map only unsupported XSD types to a SOAPElement object. By selecting this option, the emitter maps everything to SOAPElement objects. This allows you to choose an alternative XSD to Java mapping, such as EMF or SDO, and apply their mapping consistently across the entire Service Endpoint Interface.
Do not overwrite loadable Java classes. When selected, the Web Service wizards will not write any Java classes to the target project that both:
do not already exist in the project
do exist in a project, module or JAR file that will be loadable from the target project when the application is running on the server.
If this option is not selected, the wizards may write Java classes to the target project that will mask preexisting classes with the same name in other projects, modules or JAR files. This can result in run-time environment and compilation errors.
A problem currently exists in that after adding a Handler in the Handler Configuration wizard, the wizard will generate a new skeletal Handler Java file into the primary source folder of your project unless a Handler Java file already exists at the same exact location and you have not selected "Do not overwrite loadable Java classes." The wizard does not check for existence of a Handler of the same fully qualified name elsewhere in the EAR. As a result, when you use the wizard to add a Handler that already exists somewhere else in the EAR, such as in a different source folder in your project or in a different module in the EAR, the wizard will write a new skeletal Handler, eclipsing your original Handler class. If this occurs, delete the skeletal Handler generated by the wizard.

Use the WebSphere v5.1.1 Web service emitter when you have selected the WebSphere v5.1 Application server as your Web service server target. The Web services tools cannot detect which version of the WebSphere Application Server to which you are targeting your Web service, so it is important to choose the correct level of emitter for your server version. If you leave this check box deselected, the tools will generate code using the WebSphere v5.1.0 emitters and this code will function on either WebSphere Application Server v5.0.1 and v5.1.1. If you select the check box, the WebSphere v5.1.1 emitter will be used, and this code will only compile on WebSphere Application Server v5.1.1.

Note when generating element-based mapping when using the IBM SOAP run-time environment:

When using the IBM SOAP run-time environment, the Web services wizard is now fully enabled to generate element-based mappings, in addition to any of the normal type-based mappings, if the "Enable element-based mapping" is selected.

If this preference is not enabled, which is the default, the Apache/IBM SOAP run-time environment may not interoperate with other vendors' Web service run-time environments that send messages whose elements do not have "xsi:type" properties. Web service run-time environments from other vendors follow various policies on the inclusion of xsi:type properties. Some always include them. Some never do. Some provide a configuration choice. Some omit xsi:types for certain types, like arrays.

The typical error produced by the IBM/Apache SOAP run-time environment is:
targetException=java.lang.IllegalArgumentException: No Deserializer found to deserialize a ':MyElement' using encoding style 'http://schemas.xmlsoap.org/soap/encoding/'. When enabled, element-based mappings are generated into:
the deployment descriptor file for bottom-up Java bean/EJB scenarios and WSDL Skeleton scenarios
the Proxy in client scenarios

Element-based mappings are of the form:
<isd:map encodingStyle="encoding style" xmlns:x="some-namespace" qname="x:some-local-name" xml2JavaClassName="some-deserializer-class-name"/>
An element-based mapping is generated for:

Each part defined in each wsdl:message input.
Each part defined in each wsdl:message output, for Skeleton and Proxy scenarios only.
Each root element or local element in each complex type referenced by parts in the WSDL file

The WSAD Web services wizard follows the SOAP and XSD specifications to determine whether or not the element name in an element-based mapping should be qualified (that is, have a namespace) or unqualified.

The WSAD Web services wizard follows these rules for deciding between qualified and unqualified element names:

Part names in WSDL yield unqualified names.
Root elements in XSD yield qualified names.
Local elements in XSD yield unqualified names if the schema specifies elementFormDefault="unqualified", which is also the default if the schema has no elementFormDefault attribute.
Local elements in XSD yield qualified names if the schema specifies elementFormDefault="qualified".

Some run-time environments are known to generate unqualified elements in SOAP messages despite a schema that specifies the use of qualified elements via the XSD schema's "elementFormDefault" attribute. In such cases, you may need to hand-edit a service's WSDL or XSD and change elementFormDefault to "unqualified".

An example of a non-namespace qualified element-based mapping is:

<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="" qname="x:name" xml2JavaClassName="org.apache.soap.encoding.soapenc.StringDeserializer"/>

An example of a namespace qualified element-based mapping is:

<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="http://www.ibm.com/" qname="x:name" xml2JavaClassName="org.apache.soap.encoding.soapenc.StringDeserializer"/>

Please note that only one element based mapping will be generated for a given element name. That is, if the schema uses the same element name more than once but with different types, only one of the elements will be selected, effectively at random, as the basis for one element-based mapping. The other identically-named elements of different types will fail to deserialize. The same is true if the schema uses the same name for an element and for a WSDL part.

When beginning with a service bean which returns an array of Map or an array of Hashtable, and the "element-based mapping" option is enabled, the generated SOAP Proxy will incorrectly map the return type to a java.lang.String[]. A ClassCastException will occur during run time. To work around this problem, run the Web service client wizard with the newly created WSDL and regenerate the SOAP proxy into the client project.
If you select the Web services code generation preference "Enable element-based mapping" and you selected to deploy to a WebSphere Application Server V4, you may get the following entry in the ISD file and dds.xml:
<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:x="" qname="x:some-name" xml2JavaClassName="some-serializer"/>

The XML editor may flag the following error:

The value of the attribute "xmlns:x" is invalid. Prefixed namespace bindings may not be empty.

This is harmless for the WebSphere Application Server V4. However, do not attempt to deploy this dds.xml to other server which uses Xerces 2.x (XML4J 4.x) or higher such as WebSphere Application Server V5. Otherwise, you will get similar Xerces parse error when the server loads the dds.xml file. You should regenerate dds.xml by going through the Web service scenario and selecting the right server type. This will generate the correct dds.xml for that server type.

Also, you would get similar Xerces parse error when attempting to deploy Web service from that ISD file. The workaround is to manually edit the file to the following format:

<isd:map encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" qname="some-name" xml2JavaClassName="some-serializer"/>

JDBC Drivers

The JDBC Drivers preferences enables you to add JAR files for JDBC drivers. On Linux, it can be difficult to determine the location of the JAR file containing JDBC drivers. Therefore, this preference was added so that you can specify which JAR file to use. This is used only by the DADX validation code on Linux.

Popup Dialog Selection

The Dialogs preferences enable you to determine which dialog boxes that you want to see when running popup actions. If you have disabled any of the dialogs by selecting "Do not show this dialog again" on the first page of a Web services wizard, you can undo your change by clearing the check box beside the dialog that you have chosen to hide.

Private UDDI Registry

Use this page to set the UDDI category data column and string delimiters.

Project Topology

The Project Topology preferences allow you to:
Select the default client project type that the Web services wizards will create when generating a Web service client. You can also set the order in which the client project types will be listed in the wizard. Note that this selection is simply a default and an alternate project type can be selected in the wizard.
Select whether you want to generate the Web service and the Web service client in the same EAR project or different EAR projects. Generating the service and client into different EAR projects can reduce the chance of conflicts that occur when both exist in a single EAR project, but uses more system resources.

Resource Management

The Resource Management preferences enable you to determine the file and folder creation and overwriting defaults that you want to use when creating your Web service.

Scenario Defaults

The Scenario Defaults preferences enable you to set the following scenario defaults that you want to use when creating your Web service:
which type of Web service you want to be selected by default.
whether or not you want the Web service started by the wizard.
if you want the Web Services Explorer to launch by default so that you can publish your Web service to a UDDI registry.
if you want to generate a proxy and the default type of proxy generated.
if you want the Web Services Explorer to launch by default so that you can test the Web service.
if you want the Web service SOAP traffic routed through a TCP/IP monitor so that you can monitor the SOAP packets and optionally test them for WS-I compliance.
Note that all these defaults can be overridden in the wizard.

Server and Runtime

Select the server, Web service run-time environment, and J2EE version that you want selected by default in the Web services wizard. Note that all these defaults can be overridden in the wizard.

SOAP Transports

Select your default transport: SOAP over HTTP or SOAP over JMS. This preference only applies if you are using Web services that use the WebSphere run-time environment.

Test Facility Defaults

can select whether to have the wizard automatically launch a test facility, and you can select your preferred type of test facility

Web Services Explorer

The Web Services Explorer preferences allow you to select whether or not to ignore schemas for SOAP arrays. This is suggested when testing Web services that use the IBM SOAP run-time environment.

WSDL files

When creating a WSDL file in the WSDL editor, you can set the default target namespace. If you do not select to change the default, your WSDL file will have http://tempuri.org as its target namespace.

WS-I Compliance

The WS-I Compliance preferences allow you to select your level of compliance with the WS-I Simple SOAP Binding Profile (SSBP) and WS-I Attachement Profile (AP). This preference applies mainly to Web services that use the WebSphere run-time environment. Web services using the IBM SOAP run-time environment and Apache Axis run-time environment are normally not WS-I compliant. Note: if you change the level of WS-I compliance while WS-I incompliances are listed in the Task view, the Task view will not be automatically updated. The workspace must be revalidated before the warnings will be removed from the Task view.

Parent topic
Web services overview

Related Concepts
Tools for Web services development

Related Tasks
Developing Web services