What are the various aspects of JAX-RPC Web services code generation in Rational Application Developer v6.0 and v7.0, with an emphasis on changes for version 7.0?
This information can serve as a useful resource for Web services developers.
Web Service code regeneration and Deploy
Files are regenerated when you re-generate the Web service using the wizards or do a Deploy. Deploy does not generate all the files that the Web services wizard does during a complete regeneration.
Web Services deployment descriptor files like ibm-webservices-bnd.xmi and webservices.xml are generated by our WSDL2java invocation in the RAD wizard so it should be treated the same as any other development code. These files and any generated Web services development code do get regenerated every time in the wizards.
Clarification of "Deploy"
It is important to clarify what is meant by Deploy. There is a distinction between development and deployment artifacts.
When wsdl2java is invoked in development mode, it will generate skeletal deployment descriptors (JAX-RPC mapping file, webservices.xml, webservicesclient.xml, as well as Web, EJB and Application Client deployment descriptors, ibm-webservices*.xmi) along with development time Java artifacts. The deployment descriptors are merged with any existing ones so settings for other Web services and clients are preserved.
During deploy (as in wsdeploy), only container specific deployment time Java™ code is generated. For WebSphere JAX-RPC, this typically includes serializers, deserializers, deser proxies (for exceptions), *Information.java and *Locator.java (for clients). No deployment descriptors are generated nor updated during wsdeploy. More on this in issue 3. under Specific to RAD v7.0.
Before continuing, a useful complement to the overall topic of web services code generation in RAD are the following articles, under Related information:
- IBM Rational Application Developer Web services tooling tips and tricks: Part 1: Be aware of the preferences page
- IBM Rational Application Developer Web Services Tooling Tips and Tricks: Part 2: Validate Java classes for compliance to JAX-RPC
They provide a very good explanation of IBM WebSphere® runtime and other options in the RAD v6.0 and v7.0 Web Services Preferences page. Especially relevant to Part 1 is the background article on WSDL SOAP style bindings such as document/literal wrapped:
- Which style of WSDL should I use?
|Issues involving Web services code generation in RAD|
The following topics can be useful to Web services developers.
- The way to delete the existing Web services generated artifacts and to regenerate the Web services cleanly is discussed in technote 1238597: Deletion of a Web Service or of Web services from a project and regeneration
The workaround of deleting all of the existing Web service items in a project and thus cleanly regenerating a Web service helps to resolve many problem scenarios, when you are uncertain of what has accumulated in a project and is resulting in a nonfunctional Web service.
- When a Web services project is managed with Rational ClearCase, certain files may be marked as Read-only.
When generating the web service, RAD with Rational ClearCase® wants to check-in ibm-webservices-bnd.xmi as well as a few other related Web services Deployment Descriptor files.
If these files already exist in ClearCase, the RAD Web service tools may complain that these files do not have write permission, only read permission. This can prevent the Web services generation from completing.
Files checked into ClearCase are read-only and should be checked-out from ClearCase before regenerating or redeploying a Web service/client, or add the files to the ignored resources list in the case of temp files.
In the case of the Web services deployment descriptors and their IBM extensions: webservices.xml, ibm-web services-bnd.xmi, ibm-webservices.xmi, webservicesclient.xml, ibm-webservicesclient-bnd.xmi, ibm-web servicesclient-ext.xmi, some of the Web services wizard commands will not work with such files being Read-only files.
In RAD v6.0 there are also temporary/temp copies of the existing deployment descriptor files:
In the case of the ClearCase read-only scenario if the temp copy already existed, the backup would fail. More importantly, the "ibm-webservices*-*-temp.xmi" and webservices-temp.xml files are temporary files used by the RAD v6.0 Web service wizard and should not be checked into ClearCase. There is also the option of adding them to the Ignored Resources list under the Team preferences: Window > Preferences > Team > Ignored Resources.
The Rational Application Developer V6 Programming Guide (see Related information)
in Chapter 25 Rational ClearCase Integration has useful information on these preferences:
- 25.1.4 ClearCase preferences
includes a screen capture (Figure 25-2) with the preferences.
- 25.3.1 Enable Team capability in preferences
The Information Center items for RAD v6.0.1, Ignored Resources, and for RAD v7.0, Ignored Resources, explains this preference.
As of RAD v7,0 , there are no such temp files in a project. Additionally, as of RAD v184.108.40.206 Ifix003a and later (APAR JR24077), a defect was fixed, in that the Web services wizards were not reporting their failure to overwrite files due to them being marked read-only (or to actually try checking out the file thus making it not read-only).
- Derived/generated files should not "normally" be checked into any SCM such as ClearCase or CVS.
- Derived/generated Web services:
The Properties dialog for any file (right-click > Properties) in RAD v6.0 or higher has a checkbox to show if the file is derived and, as such, should not be checked into a Source Configuration Management system (SCM) such as Rational ClearCase.
The Web services generated deployment java files (for example, *_ser.java, *_Deser.java, *_helper.java) are not marked as derived in RAD v6.0. The same is true for RAD v7.0 in most cases, and is discussed later. The implication being they should normally be checked. It is generally the serializers, deserializers and deser proxies that do not need to be checked in as they are runtime container specific deploy artifacts as was explained earlier in Clarification of "Deploy". These typically have names *_Ser.java, *_Deser.java and *_DeserProxy.java, and could be manually marked as derived. Similarly on the client side you will also have *ServiceInformation.java and *Locator.java.
For more information on generated Web services files for WAS v6.x see (under Related information):
WebSphere Version 6 Web Services Handbook Development and Deployment
- Chapter 16: Develop Web services with Application Developer
-> Creating a Web Service from a JavaBean
--> Generated Files: Fig 16-10 Wizard-generated files in the Project Explorer .
See also the Generated code information for the other specific "Creating a Web service ..." scenarios in Chapter 16.
Web Services Handbook for WebSphere Application Server 6.1
- Chapter 15: Develop Web services with Application Server Toolkit 6.1 (RAD v7.0 is based on AST v6.1)
-> Creating a Web Service from a JavaBean
--> Generated Files: Fig 15-10 Wizard-generated files in the Project Explorer. See also the Generated code information for the other specific "Creating a Web service ..." scenarios in Chapter 15.
- Specific to RAD v7.0:
When you generate a top-down web service from a WSDL, all of the Java files are generated by the Web Service Wizard which performs a one-pass code generation for performance reasons. Files will not be marked derived , except for deployment files in one case.
In RAD v7.0 and beyond, you can use the page 1 slider in the Web services wizard to select the phase. You would choose Develop or Assemble to generate the development side code but not the deployment code. When you set/raise the slider to Deploy or Install the service, the deployment files are generated but not marked as derived. If you set the slider higher to Start the service they are generated and marked as derived.
When Adding an EAR project with a Web service project or projects to the server, without deploy/deployment side files already generated, the deployment files: *_Ser.java, *_Deser.java, *DeserProxy.java, and on the client side files: *ServiceInformation.java and *Locator.java are generated. If the Web services projects did not have deployment files originally, the newly generated deployment files would now be marked as derived. If the deployment side files had existed prior to adding the EAR project to the server, and they were not marked derived, they would not be marked as derived.
Invoking Prepare for Deployment (that is, a manual Deploy) on a Web service project without deployment files, will generate deployment side code and mark the files as derived.
Invoking Prepare for Deployment on a Web services project with deployment files not marked derived, as per the previously mentioned Wed services wizard scenarios, will not mark the files as derived.
Prepare for Deployment will always regenerate and mark the deployment files as derived (if not done so before) if Window > Preferences > J2EE > Perform Incremental Deployment is off (unchecked).
- Derived/generated Web services:
- Regenerating Web services on Deploy
A customer concern has been that deployment files are always re-generated on deploy to the server or manual Prepare for Deployment, even if they are unchanged. Additionally, any such files, not marked as derived, are also repeatedly checked into an SCM such as ClearCase. It cannot be resolved with 100% certainty when a Deploy will be triggered. Here is a basic explanation of what RAD Web services tooling does when Window > Preferences => J2EE => Perform Incremental Deployment is on or checked:
If you start RAD v6.0 (or v7.0), all workspace resources (that is, files) are assumed to be undeployed. Adding an EAR to the server, a manual Deploy or "other" actions may trigger a deploy resulting in code regeneration of deployment files and the project to be marked as deployed. It is not always clear what these "other" actions may be, but it is possible that actions higher up in say RSA v7.0 modeling or other tools involved with Web services in RAD or RSA may cause deployment to take place.
When certain changes occur in a project, RAD marks the project undeployed again. Changes that trigger this are the following:
- New Java files
- Changes to existing Java files
- Changes to deployment descriptors
- Deleting deployment descriptors or Java files
An enhancement was delivered in RAD v7.0 so that even if code is generated, RAD Web services tooling will check against existing source and try to prevent unnecessary checkouts and copying (as appropriate). If the re-generated code is different then the original/existing deploy code, it will be replaced. Otherwise the Disable Deploy on Publish feature , discussed next, may be useful: ...
- RAD v220.127.116.11+ and v7.5.1+ Disable J2EE Deploy on Publish feature:
As of the RAD v18.104.22.168 fix pack update, there is a RAD v7.0 Eclipse configuration specific system property to disable code generation, introduced under APAR PK46870: CODE REGENERATED WHEN WSDL HAS NOT BEEN TOUCHED.
The property is: DISABLE_PUBLISH_GEN_DEPLOYCODE
You need to edit:
<RADv7.0.0.x Install Dir>\SDP70\configuration\config.ini and specify the system property as follows:
Make a backup copy of the config.ini file before modifying it.
In RAD v22.214.171.124 it is a specially activated feature enabled using a system property that needs to be manually set. There is no other way.
The APAR PK46870 fix feature was created to just disable code generation during publishing. The key point is that this system property disables any code generation when doing a publish, on any publish.
If changes are made to the web service, then it will be necessary to run "Prepare for Deployment" on the project to pick up the changes.
In RAD v7.5.1+ (not in 7.5.0) , you can enable this property on a specific server in the Servers view in the Server "Overview" editor under:
Publishing > Select enabled publishers: [x] Deploy J2EE Modules.
Deploy J2EE Modules is checked by default, indicating a Deploy is done on publish (typically when you "Add" an EAR to the server). Uncheck this box to disable Deploy on publish to the server
Important Note: The concern with this property is that changes could be missed (especially from changes higher up in RSA v7.x modeling tools or elsewhere in RAD 7.x) and without a re-deploy with code generation it could lead to problems on the server. If you choose to "disable Web services code generation on deploy", the previously mentioned project changes or triggers that could mark the project undeployed should serve as a guide as to when you should manually redeploy ( == Prepare for Deploy) the contents of the project. If ever in doubt as to whether a change has occurred or not, regenerate.
- Guidance on upgrading to new WebSphere server versions and regenerating the Web services code.
It should not be necessary to regenerate a JAX-RPC web service in which no changes are planned when upgrading servers, unless a defect or error is encountered at runtime on the newer WebSphere server version.
For example, when upgrading servers from WAS v5.0.2.x (J2EE 1.3 JAX-RPC Web service) to WAS v6.0.2.x to WAS v6.1.0.x , or from WAS v5.1.1.x (J2EE 1.4/J2EE1.3 JAX-RPC web service) to WAS v6.0.2.x to WAS v6.1.0.x, if a runtime error is encountered it should first be submitted to WAS web services Support for feedback before proceeding with code regeneration.
Note: If installing a Web services EAR to a new version of a server, be sure to uncheck the Deploy Web Services option ( == wsDeploy) in the admin console, to prevent unwanted code deploy/regeneration.
As of the time of publishing this technote there is no WAS v5.x or v6.x Information Center documentation that mandates Web services code must be regenerated between major WebSphere releases (V5,x vs. V6.x). The WAS v6.x Information Centers provide these specific migration items:
WAS v6.1 - "Web services migration best practices"
WAS v6.0 - "Web services migration best practices"
For example, they discuss deprecated specifications and APIs and provide recommendations.
If you are planning to move from a JAX-RPC to JAX-WS (as of the WebServices Feature Pack for WAS v6.1) you will need to completely change and regenerate the Web service.
The RAD v7 Information Center (see Related information below) also provides:
Hints and tips for migrating Web services
The WAS v6.x and RAD Information Centers offer many specific items on migrating Web services. Search on migrating Web services
The decision to regenerate should be based on issues such as the need for more recent specification compliance in your web service, or if runtime errors are encountered as mentioned above. At the same time, WebSphere v6.x still supports running J2EE 1.3 Web services and clients, typically coming from WAS V5.x. WAS V5 is JAX-RPC 1.0 compliant and WAS V6 is JAX-RPC 1.1 compliant, there were changes how some java-xml and xml-java mappings were implemented in WAS V5 versus WAS V6. More specifically:
- WAS V6 WSDL2Java/Java2WSDL generates J2EE 1.4 (JAX-RPC 1.1) code.
- WS-Security 1.0 is supported only with J2EE 1.4 applications. A draft version of this spec is supported with J2EE 1.3.
- Fix updates early on in the WAS 6.0.x stream that may have caused older deployment stubs to no longer resolve against changes made in the WAS web services runtime internal API. Even so, this would justify at most redeployment, not complete regeneration, of the Web service; and could be recommended only if the Web service exhibit problems post-migration. If in doubt consult WAS web services runtime support.
- RAD v7.0:
How Rational Application Developer version 7 uses the WebSphere Web services emitters
- RAD v6.0:
How to replace Web services.jar (== java2wsdl, wsdl2java, wsdeploy, endptenabler) in the WAS version 6.x Web services deploy plug-in
Note: During migration that is implemented in WebSphere server product during WebSphere installation/upgrade, Web services code is regenerated. Consult WAS support for specifics. If you have issues such as coexistence in WebSphere V5 and V6 mixed node environment during the migration, consult WAS Support.
In the case of a manual WebSphere migration (installation and deployment to a new WAS v6.x) of an EAR that was originally packaged and deployed in V5 and you need to regenerate Web services code, do so in RAD v6.0 or v7.0 for the desired target WAS V6.x release and then deploy it to that WebSphere V6.x server [through the Administrative (Admin) Console or wsadmin]. In this case the Deploy Web Services option in the admin console can be unchecked because Web Service code was already regenerated in RAD v6.0 or v7.0.
If RAD v7.0/v6.x has an older version of wsdl2java/java2wsdl emitters than the stand-alone WebSphere V6.x release targeted for test or production then it may be necessary to regenerate Web services code thru the "Deploy Web services" checkbox during deployment or to upgrade RAD v7.0/v6.x so that it uses the same version of wsdl2java/java2wsdl tool as shipped with a stand-alone WebSphere V6. In the case of RAD v7.0 it uses the emitters from the WAS v6.x server installed with it and the server can be upgraded to the desired level (just as for a stand-alone server). Options also exist for RAD v6 emitters and you should consult RAD Support. Specific information is provided in the following RAD Web services emitter technotes:
As of the RAD v126.96.36.199 fix pack update there is a RAD v7.0 specific system property to provide support for the WSDL2Java -all option, introduced under APAR PK54578. Details are in the technote:
Rational Application Developer v188.8.131.52 and later provides JAX-RPC WSDL2Java -all option.
|18 November 2008||Fixed Type in property name|
|4 January 2008||Added Note to Introduction|
|3 January 2008||Initial publication|
All statements regarding IBM future direction or intent, including current product plans, are subject to change or withdrawal without notice and represent goals and objectives only. All information is provided for informational purposes only, on an "as is" basis, without warranty of any kind.
Rational Application Developer v7 Programming Guide
RAD v6 Information Center
RAD v7 Information Center
WebSphere v6 Web Services Handbook Development and Depl
Web Services Handbook for WAS 6.1
RAD Web Services...Part 1: Be aware of the preferen
RAD Web Services...Part 2: Validate Java classes fo
Which style of WSDL should I use?
How RAD v7.0 uses the WebSphere Web services emitters
RAD v184.108.40.206+ PK46870 DISABLE_PUBLISH_GEN_DEPLOYCODE
RAD v220.127.116.11+ provides JAX-RPC WSDL2Java -all option
|Software Development||Rational Software Architect||Linux, Windows||6.0|
|Software Development||Rational Web Developer for WebSphere Software||Linux, Windows||6.0|