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

Exception-handling in JAX-WS Web Services on WebLogic

There is more to exception-handling in JAX-WS Web Services than meets the eye. Especially when throwing custom (checked) exceptions from your Java methods that are exposed as Web Service operations. There’s a nice blog by Eben Hewitt on using SOAP Faults and Exceptions in Java JAX-WS Web Services. I recommend reading it; especially when you get the following error: javax.xml.ws.soap.SOAPFaultException java.lang.NoSuchMethodException. This is one of the issues you might run into when migrating from Oracle Application Server (OC4J) to Oracle WebLogic Server.

Best practices 3 – Oracle ESB and Mediator

This is the third post in our SOA and BPM best practices series. This blog provides best practices for Oracle ESB (Oracle Fusion Middleware 10g) and its successor (when it concerns routing and transformation): the mediator component in SCA (Oracle Fusion Middleware 11g). The previous blog in this series is about Web Services best practices.

Use a bus. Maybe a bit of an open door, but there are still projects that stall, exceed budget, or fail all together since no ESB is used and “SOA-plumbing” is implemented (or tried at least) in an orchestration tool, custom logic, and so on. Use an ESB for decoupling, virtualization, abstraction, transformation (data as well as protocols), and content-based routing. Decouple this type of functionality from your orchestration and workflow.

Migrating from OFM 10g to OFM 11g.

• If you don’t migrate to SCA and have used Oracle ESB as a stand-alone ESB then migrate to OSB. This will require reimplementation of OESB flows as OSB flows.

If you migrate to SCA:

• For non-reusable ESB flows that perform “internal” transformation and routing functionality within the SCA runtime: create a mediator component that is not directly exposed in its containing SCA composite and add your other components that use the mediator -such as BPEL components- to that composite. Open the OESB project in JDev 11g to create an initial composite.
• For reusable ESB flows that perform “internal” transformation and routing functionality within the SCA runtime: create a composite containing only one mediator component that is exposed using a service. Other SCA composites can reuse this “mediator” composite. Open the OESB project in JDev 11g to create an initial composite.
• For ESB flows that interact with the “outside world”; in other words connect the SCA runtime to other runtimes and/or external parties such as suppliers and clients: migrate to OSB.

Encapsulation and exposing operations. As with Web Services in general, do not expose all routing service operations and adapter operations. This promotes encapsulation; only expose what is or will be reusable. Also see this post about improved encapsulation in OFM 11g. In 10g, you cannot “hide” an ESB flow but you can minimize the operations that are invocable by disabling the option “Invocable from an external service”. In 11g, you can hide a mediator within its composite by not directly exposing it by making sure there’s no direct service and wire to it. This is achieved by disabling the “Create Composite Service with SOAP Bindings” option when creating a mediator component.

Data enrichment. Although data enrichment typically is something you would do in an ESB -for example when implementing VETO (validate, enrich, transform, and operate)- don’t use Oracle ESB for it. Through the lack of temporary variables it is not well suited for data enrichment when data comes from different sources. You can use the $ESBREQUEST variable to ameliorate this, but still this is not a great workaround. Use BPEL PM or OSB in 10g for complex data enrichments and OSB or SCA composites containing multiple mediator and/or BPEL components to achieve complex data enrichment.

XML. Create a public_html folder in every ESB project created with JDeveloper 10g and place non-generated XML artifacts such as XSLTs and XSDs in it. Leave generated XML artifacts such as TopLink descriptors from the DB Adapter in the (default) root folder. When editing mediators in 11g XSLT will automatically be created in an xsl directory and XSDs will be placed in a xsd directory.

Deployment. Use Oracle ESB Ant scripts to deploy to test, acceptance, and production environments. Use deployment plans to configure endpoint and adapter settings per environment (DTAP). Make sure you don’t mix Ant and JDeveloper deployment since it can cause problems in your ESB runtime. For SCA composites use configuration plans.

Structuring. Use ESB Systems and Service Groups in 10g to structure ESB flows. A possibility would be to use an ESB Systems per business domain and an ESB Service Group per project. For example: ESB System “Finance” that contains ESB Service Group “FIN_ESB_Process_Invoice”.

XSLT extension functions. Custom XSLT functions can be a powerful mechanism to implement your own transformation logic but it can also break portability when moving from one environment to the other due to the required configuration and deployment steps. The creation of user-defined extension functions in OFM 11g is different from 10g. See Appendix B of the Oracle Fusion Middleware Developer’s Guide for Oracle SOA Suite.

Clustering. Clustering of Oracle ESB is not a trivial thing to do. Only cluster if needed from QoS (Quality of Service) reasons such as high availability, failover, and throughput. Mind non-concurrent adapters such as FTP and File adapters when clustering.

Versioning. Oracle ESB 10g does not support versioning natively. You can include the version number in the ESB project name and deploy it as new flow alongside older versions. In OFM 11g mediators are part of composites and therefore versionable.

Transactionality. Transactionality -including support for XA- of ESB in 10g is dependent on several factors and can therefore be somewhat complex. These factors include the mechanism (through BPEL PM, ESB, or other technology or client), binding protocol (SOAP versus WSIF) used to invoke ESB flows, use of synchronous or asynchronous routing rules, use of different ESB Systems in an ESB project, and so on. Read Oracle’s SOA Suite Best Practices Guide and this presentation on transactions, error handling and resubmit.

Oracle’s best practices guide. Read Oracle’s SOA Suite Best Practices Guide for more tips and tricks.

Next blog in this series will be about security and identity- and accessmanagement in a SOA-environment.

Installing JDeveloper 11g

Two things I ran into when installing and configuring Oracle Fusion Middleware JDeveloper 11g that are worth mentioning:

• Setting the User Home Directory. As documented in the OFM 11g Installation Guide you can specify the user home directory which is used as default location for new projects and in which JDev will store user preferences and other configuration files. If you explicitly set this location on a Windows system using the ide.user.dir variable in the jdev.boot file, then make sure you use a notation like D:/workspace/ofm11g and not D:\workspace\ofm11g. Using backslashes results in the user dir [OFM 11g Home]\Middleware\jdeveloper\jdev\bin\workspaceofm11g being used instead of D:/workspace/ofm11g.
• Installing Additional Oracle Fusion Middleware Design Time Components. When installing additional OFM design time components such as WebCenter and the SOA Suite Composite Editor make sure you restart after installation of each single component. Do not install the WebCenter and SOA Suite editor without restarting in between. If you do only one of the additional components will be visible next time you start JDev.

Once you’ve downloaded OFM 11g from OTN, installation is easy and straightforward.

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).

Best practices for BPM, SOA and EDA

While visiting ODTUG Kaleidoscope 2009 in Monterey and talking to fellow BPM, SOA and EDA adepts I got this idea about creating a best practices and lessons learned blog series. This first blog is dedicated to best practices in the BPM and SOA-space based on cases from a presentation by Lonneke Dikmans. Subsequent blogs will dive into best practices and lessons learned for a specific product, methodology or technology.

Case I: Introducing BPM. Mistake: Organizational impact underestimated. Explanation: Successful delivery of BPM project, business heavily involved. Never used because they realized after delivery that changes in both the organization and the software were needed. Best practice 1. BPM and SOA are about business, IT and humans. Observe how people work, don’t just ask them.

Case II: Notifications. Mistake: Dependencies between processes modeled directly in the processes itself. Explanation: Process flow sometimes is influenced by other processes. This was modeled into every process: this makes processes tightly coupled to each other and hard to change. It resulted in deadlocks. Best practice 2. Use events to notify running processes. Best practice 3. Monitor & avoid exceptions.

Case III: New technology. Mistake: Use BPEL as a general purpose language. Explanation: BPEL is a domain specific language; it was designed to orchestrate (web) services. Someone coming from a homogeneous -for example PL/SQL environment- in their back office, could decide to rewrite everything in BPEL, even the service implementations. The progress of such a project is very slow, and doing things that used to be easy becomes very hard. Best practice 4. BPEL is a Domain Specific Language (DSL); use BPEL for orchestration only. Best practice 5. Use an Enterprise Service Bus (ESB) to expose services to consumers including BPEL. Best practice 6. Use Java for service implementation. Best practice 7. Use PL/SQL for persistent data manipulation and data integrity rules. Best practice 8. Use rules when you need customization, inference or when business rules are volatile.

Case IV: Quality of Service. Success: involve administrators early. Explanation: Someone designed their first SOA project with quality of service in mind. In production all the non-functional demands were met. Best practice 9: Design architecture for Quality of Service from the start … but only what you really need! Not everyone needs clustering, fail-over, high-availability, and so on.

Case V: Domains. Success: combine a top down with a bottom up approach. Explanation: By defining 6 business domains and one supporting domain, the service taxonomy and event definitions were easier to keep track of. Also defining an owner for some of the services and design guidelines for services that cross domains become possible. Best practice 10. Use domains and layers to facilitate making a taxonomy of services and defining design guidelines.

Conclusion. Think big, start small. Meet in the middle requires aligning Business, IT and People. Architects can be intermediaries. Sharing knowledge and experience is necessary.

The next blog in this series will dive into Web Services best practices.

ODTUG Kaleidoscope 2009

ODTUG Kaleidoscope 2009 is almost coming to an end at the time of this writing. After some chilly days the sun started to shine in Monterey and turned this great event into an even better one. As mentioned almost every day, ODTUG is one of the few conferences that has grown compared to last year. This was my first visit to ODTUG. I actually thought it would be as big as Open World :-) But it’s about a hundred times smaller. And actually that’s cool; much more intimate. Here you really get the chance to speak to product managers, interact with peers, and meet lots of new and interesting people!

So what were the highlights?

SOA and BPM Symposium on Sunday. For the first time there was a separate symposium and track dedicated to SOA and BPM. It was put together by ACE Directors Lonneke Dikmans, Lucas Jellema and Mike van Alst. Although the APEX and database tracks attracted more audience, we had a very interesting and interactive day with a mix of newcomers and SOA-adepts. The day was split into a business and technology part. Breakout sessions were mixed with great presentations by Demed L’Her, Geoffroy de Lamalle, and Clemens Utschig. Read about the results -SOA and BPM approaches- on Oracle Wiki.

Fusion Apps demo. The first official demo of the upcoming Fusion Apps. It looked really smooth! It’s build on top of the new Oracle Fusion Middleware 11g stack (WebCenter, ADF, SOA Suite). Lot’s of social networking capabilities and interaction. Expect to see more of this. Some technology stats: approximately 11,000 task flows, between 5 and 6 thousand tables, tens of thousands of ADF BC View Objects, and so on.

Oracle ACE dinner. Great dinner followed by a bonfire and s’mores on the beach!

Presentations in the SOA and BPM track. Lots of interesting presentations here. I was an ambassador for Lonneke’s presentation and did a presentation myself on SOA in a database-centric environment. Also great presentations by Roman Dobrik on BPEL development patterns, Chris Judson on canonical data models, Mauricio Naranjo on a government SOA project in Latin America, Samrat Ray on SCA in SOA Suite 11g, Mark Simpson on tools for business processes, and Lucas Jellema on SOA in an Oracle classic stronghold.

Meeting fellow geeks. You want to meet people that drive cars with license plates like “BPEL” or “WEB 2 OH”? Find them at ODTUG!

Great conference! Thanks to everyone and looking forward to meet everyone again at Oracle Open World 2009!