Posts Tagged ‘Web Services’

Best practices 2 – Web Services

This is the second post in our SOA and BPM best practices series. This blog is about Web Services and provides a mix of general tips and more specific tips for Web Services that are implemented using Java and JEE. You can find the first blog in this series here.

Approach. Decide upfront, based on the requirements and constraints, what approach for Web Service development best suits your situation: top-down or contract first, bottom-up, or meet-in-the middle.

• Top-down or contract first. The starting point here is the contract of the Web Service: its WSDL. You either design it or it is provided as a ‘given fact’. From the WSDL you generate the implementation. If the contract frequently changes, regeneration of the code can cause difficulties since the implementation is overridden. If you use this method, make sure you don’t change the generated artifacts.
• Bottom-up or implementation first. The starting point is the implementation; all Web Service artifacts“such as its WSDL’s “ are generated. This is a fast approach when you want to expose existing components as Web Service. However, you need to be careful because you have limited control over the generated Web Service artifacts and it is therefore easy to break an interface if the Web Service is regenerated.
• Meet-in-the-middle approach. Here you define both contract and implementation yourself and later on create the glue between them. In case of Java you can use JAX-WS and JAXB APIs and code to create this glue. This is a very flexible approach: you can change both the WSDL and the implementation. It requires more work in the beginning, but is easier to change later on.

Compliance. A Web Service that isn’t standards-compliant is less (re)usable. Make sure your Web Service is compliant to the WS-* standards by using the WS-I profiles (Web Services Interoperability Organization).

Exposing operations. Don’t expose all methods as Web Service operations by default when using a bottom-up or meet-in-the-middle approach. Only expose those methods that are actually needed by service consumers. This promotes encapsulation and prevents access to ‘internal’ methods.

Products. Nowadays most products and technologies support Web Services. Keep their pros and cons in mind when deciding what technology to use. Java for example provides better support and a better runtime for Web Service development and XML-processing than relational databases.

Large XML documents. Avoid creating Web Services that receive, process, and/or send very large XML documents. XML processing is resource-intensive and relatively slow and therefore not well equipped for handling bulk data. Use other technologies such as database technologies or ETL tools for that purpose.

Quality of Service (QoS). It’s easy to develop basic Web Services-but it’s hard to make them robust, secure, and scalable (enough). Address these QoS (or non-functional) issues in the beginning of the project instead of discovering that requirements are not met at the end of your project.

Annotations. Be careful when using vendor-specific annotations (as opposed to the general annotations defined in the JAX-RPC, JAX-WS, and JAXB standards). Although vendor-specific annotations such as those in WebLogic can be very powerful they break portability of Web Services and tie them to a specific runtime.

Migration to WebLogic. See this blog for migrating JAX-WS Web Services from JDeveloper 10g/OC4J to JDeveloper 11g/Weblogic. Note from the blog that a bottom-up approach was used. After migration the WSDL was changed (among others the namespaces were changed) causing the invocation to fail. This is a typical example illustrating the pros of using a top-down or meet in the middle approach.

Next post in this series will be about best-practices for Oracle ESB and Mediator (FMW 11g).

Web Services article on OTN

Oracle recently released Oracle Enterprise Pack for Eclipse (OEPE) 11g. OEPE is a certified set of Eclipse plug-ins that is designed to help develop, deploy, and debug applications for Oracle WebLogic Server. I wrote an article on OEPE’s Web Service capabilities, and more specifically its support for the JAX-WS and JAXB standards. The article includes a step-by-step tutorial, explains different approaches to Web Service development, and concludes with several best practices. You can find the article on Oracle Technology Network (OTN).

Migrating Web Services from JDeveloper 10g to 11g

Although most of the migration steps from JDeveloper 10g/OC4J to JDeveloper 11g/WebLogic are automated, there are some exceptions. One such case where you have to roll up your sleeves and do some coding are EJB 3 Session Beans that are exposed as Web Services using JAX-WS annotations. JDeveloper 10g generates a separate Java interface containing JAX-WS Web Service annotations when using the EJB 3 Session Bean Wizard and selecting the option to create a Web Service interface. Note that this option isn’t available in JDeveloper 11g, but you can right-click an EJB Session Bean and select the generate Web Service option that will give you the same result.

When migrating the JDeveloper 10g workspace to a JDeveloper 11g application -by opening the jws file in JDeveloper 11g- most of the migration work is automatically done; for example the workspace and project files are updated and existing deployment plans are converted.

If you then deploy the project to the integrated WebLogic server everything seems to deploy and run just fine. However if you expand the deployment in the WebLogic Server Administration Console you’ll see that there are no web services listed, only EJBs.

Here are some simple steps to correct this:

1. Remove the Java interface containing the JAX-WS Web Service annotations that was generated in JDeveloper 10g and remove the interface from the implements statement in the EJB Session Bean class.
2. Add a @WebService annotation to the EJB 3 Session Bean containing the following arguments: name, serviceName, and portName. Check the WSDL of the current deployed Web Service generated with JDeveloper 10g to obtain its metadata such as name, namespace, and portname. These values can be used in the new @WebService annotations of the migrated Web Service in JDevloper 11g so that Web Service clients don’t break due to different namespaces, portnames, endpoints, and so on. You can also use other annotations to influence the endpoint and WSDL of the Web Service. However mind that some annotations are WebLogic-specific and not part of the JAX-WS standard.
3. Optionally add other JAX-WS annotations as needed.
4. Replace the JAX-RPC project libraries with the JAX-WS Web Services library.
5. The current WebLogic JAX-WS stack -more specific the JAXB implementation- does not support java.util.Map and java.util.Collection family types as Web Service method return or input types. Deployment fails with the message “java.util.Map is an interface, and JAXB can’t handle interfaces” and “java.util.Map does not have a no-arg default constructor”. A logical workaround would be to replace these types with concrete implementations that have a no-argument constructor; for example java.util.HashMap. Although deployment then succeeds, the information contained in the map is lost at runtime when requests/responses are (un)marshalled. A final workaround was to replace the java.util.Map with a two-dimensional array. Although I’m not really happy with this workaround, it works for now.

Deploy the project and voila, the WebLogic Server Administration Console shows both EJBs and Web Services.

So “no coding required”, or just a little bit perhaps ?

P.S. Some useful links:

• Oracle-By-Example “Building Web Services” in JDeveloper 11g
• JDeveloper 11g Release Notes for Web Services Development