Headless Build Automation for Netbeans BPEL Projects

There is a great deal of mystery surrounding the Netbeans/Glassfish/OpenESB build process. I'll include here a few details for others that may be interested, but it appears that a headless build is not possible or practical at this time. If you're looking for a solution, you won't find it here.

When I first started using Netbeans I was encouraged that it used ant for its builds rather than some process implemented as part of the IDE. However, in practice, doing a build outside the IDE turns out to be not only non-trivial but extremely complex, and may be impossible in some cases. For example, in the case of a BPEL project that includes a WSDL dragged into the BPEL editor from another project...

When a WSDL from a separate project is included in a BPEL, the tag's location cause looks like this:

<import namespace="http://myns" location="otherProject/my.wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>

where "otherProject" is the project containing the web service being used. WSDLs from the local BPEL project look like this:

<import namespace="http://myns" location="my.wsdl" importType="http://schemas.xmlsoap.org/wsdl/"/>

This location tag is not an operating system file path. "otherProject/" in the above example can be anyplace on the system relative to the project being built and the the IDE somehow finds it. Using "file://something" in the location tag is apparently a syntax error. It's hard to say what this location tag actually is. At the moment, I don't know.

Outside of the IDE, a location tag such as the above fails to find the WSDL file during the build. The failure occurs in at least two java classes that the build script invokes.

org.netbeans.modules.bpel.project.anttasks.cli.CliValidateBpelProjectTask
org.netbeans.modules.bpel.project.anttasks.cli.CliGenerateCatalogTask

Somehow these classes are able, in the IDE, to map the location tag to a physical WSDL file. The only reference I could find to these location strings is in the catalog.xml file in the project's base directory. But removing these does not create a build error in the IDE, so that can't be how it knows. Is there some internal database in Netbeans tracking these references? Hard to say.

A good deal of essential information on building Netbeans projects outside of the IDE can be found here:

http://blogs.sun.com/tronds/entry/creating_a_simple_headless_build

This information is vital to getting started with the build environment, outside the IDE. That setup may be enough for most projects, or at least projects other than BPEL projects that refer to WSDLs in other projects.

GUI-only builds is a very surprising limitation, but there it is. It seems we will have to replace the build scripts for our projects. It would have been better to know about this a long time ago, before beginning projects using this otherwise really quite nice technology.

Marshalling and Unmarshalling Without a @XmlRootElement

Netbeans has a handy feature off on the palette on the right (usually) of the code editor, where you can drag a marshal or unmarshal object into your Java code and it will generate marshal/unmarshal code for the XML or JAXB object of your choice.

It is interesting that sometimes, although it does not complain when generating these code fragments, there will occur an error at runtime stating that an object has no @XmlRootElement.

@XmlRootElement annotations are not always created in JAXB objects. Here is a nice explanation of why that is:

http://weblogs.java.net/blog/kohsuke/archive/2006/03/why_does_jaxb_p.html

The subject of this post is not why this happens, but rather how to deal with these objects when you don't want to use inline complex types.

Here's a sample marshal method more or less as generated by the wizard of Netbeans:

private String jaxbMarshalToString(MyType jaxbObj) throws javax.xml.bind.JAXBException, java.io.IOException 

{
java.io.StringWriter sw = new java.io.StringWriter();
javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(jaxbObj.getClass().getPackage().getName());
javax.xml.bind.Marshaller marshaller = jaxbCtx.createMarshaller();
marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_ENCODING, "UTF-8");
//NOI18N
marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
marshaller.marshal(jaxbObj, sw);
sw.close();
return sw.toString();
}
Here is an unmarshal method for the same object:

private MyType jaxbUnmarshalFromString(String str) throws javax.xml.bind.JAXBException 

{
MsgQMessageType ret = null;
javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(MyType.class);
javax.xml.bind.Unmarshaller unmarshaller = jaxbCtx.createUnmarshaller();
ret = (MyType) unmarshaller.unmarshal(new java.io.StringReader(str));
//NOI18N
return ret;
}
This object has "Type" appended to its name. That is a sign that this is a container rather than the JAXB representation of the XSD itself. These methods fail at runtime because the object jaxbObj includes no root annotation.

Here are these two methods changed so they work. In the first method, we create a new JAXBElement (so it will have a root element) and marshal that. In the second method, we unmarshal to a JAXBElement, and return that object's getValue(), cast to our desired type. Also in the unmarshal code, the context is created using getPackage().getName() rather than just the class.

private String jaxbMarshalToString(MyType jaxbObj) throws javax.xml.bind.JAXBException, java.io.IOException 

{
java.io.StringWriter sw = new java.io.StringWriter();
javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(jaxbObj.getClass().getPackage().getName());
javax.xml.bind.Marshaller marshaller = jaxbCtx.createMarshaller();
marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_ENCODING, "UTF-8");
//NOI18N
marshaller.setProperty(javax.xml.bind.Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
marshaller.marshal(new JAXBElement(
new QName("http://www.namespace.com/schema/My", "My"),
MyType.class, jaxbObj), sw);
sw.close();
return sw.toString();
}

private MyType jaxbUnmarshalFromString(String str) throws javax.xml.bind.JAXBException 

{
JAXBElement ret = null;
javax.xml.bind.JAXBContext jaxbCtx = javax.xml.bind.JAXBContext.newInstance(MyType.class.getPackage().getName());
javax.xml.bind.Unmarshaller unmarshaller = jaxbCtx.createUnmarshaller();
ret = (JAXBElement) unmarshaller.unmarshal(new java.io.StringReader(str));
//NOI18N
return (MyType)ret.getValue();
}

Netbeans Project File Madness

Image via WikipediaFor the longest time one of my Netbeans targets was haunted by a component that I had long ago removed and moved to a different project. What would happen, a lot, is builds would suddenly fail with a message like this:

[ERROR] file:/C:/MyProject/EJBs/src/conf/xml-resources/web-services/ThatEJB/wsdl/ThatEJB.wsdl is unreachable

Failed to parse the WSDL.
C:\MyProject\EJBs\nbproject\jaxws-build.xml:112: wsimport failed

This was in spite of the fact that I had removed the target using the IDE, as "by the book" as possible. It should have cleaned up its target references, but obviously did not, and it just wouldn't let go.

What I had to do was open up C:\MyProject\EJBs\nbproject\jaxws-build.xml and remove all the references to the ThatEJB target. I had to do this once a week or so in fact, as the jaxws-build.xml file sometimes gets rebuilt (I don't know what triggers this rebuild, it doesn't seem to happen all the time).

I finally found the true source of the reference. I had to edit this file:

C:\MyProject\EJBs\nbproject\jax-ws.xml

This file contains an XML block for, it seems, each EJB, including ThatEJB. I completely removed that particular XML block. Problem solved.

Context Roots for EAR Files in Glassfish

Image by UniqueOo Mania via FlickrAfter deploying a Java Enterprise Archive (EAR) file to a few different Glassfish instances, I found that the context root of an Enterprise Java Bean (EJB) in the application varied from server to server. It took awhile to determine how Netbeans and Glassfish set this part of the URL - although I still don't know why the (default?) paths varied.

It turns out that when using an EAR file, it doesn't matter what you put in the WSDL, in web.xml, or in sun-web.xml. The context root is controled instead by application.xml. In Netbeans, right-click on the enterprise application (EA) project, and select new and “Standard Deployment Descriptor”. This will create an application.xml file, in the project, based on your current web.xml. This application.xml file can be edited to set the context root.

When using a WAR file, the context root is controled by the usual deployment descriptor, as one might expect. An easy why to set a WAR file's context root, after deployment, is through the Glassfish server administration console. Go to "Applications" and "WebApplications" (on the left side of the administration page), click on the name of your application and you’ll be able to change the "Context Root" option. Then click “Save”.

Creating a Timer EJB for OpenESB/Glassfish

Image by denis collette via FlickrThis example shows the creation of a timer for an OpenESB application, created using Glassfish. A timed code fragment will execute every 30 seconds. This example uses an EJB implementing TimedObject as the timer itself. The timer is started from a lifecycle method in a servlet as the EJB timer can not be started from EJB lifecycle methods, in the current implementation.

Here's the tools:

Product Version: NetBeans IDE 6.1 (Build 200805300101)
Java: 1.6.0; Java HotSpot(TM) Client VM 1.6.0-b105
System: Windows XP version 5.1 running on x86; Cp1252; en_US (nb)
Userdir: E:\openesb\.netbeans\openesb

glassfish-v2-ur2-b04-patch-20080729

1) Create an EJB with a local interface in an EJB project. Call the EJB EJBTimer.
2) Create a servlet in a web application project. Call it Watch.
3) create an enterprise application project and add both of the above
4) In the servlet code, right-click and use the wizard to add a reference to the EJB. It will generate this:

@EJB
private EJBTimerBean eJBTimerBean;

5) Add to the servlet code an init() lifecycle method, and include there a call to the EJB to start ticking (see the source below).
6) Modify the servlet's deployment descriptor to create the servlet on deploy. In Glassfish, it's web.xml editor calls this "Startup Order". Fill in a one. Examine the "load-on-startup" tag in the web.xml, to see what this does.
7) Deploy the enterprise application. The servlet will be created and will start the timer.

Here is the timer EJB:

package com.me.ebj;

import java.util.Date;
import javax.annotation.Resource;
import javax.ejb.Timer;
import javax.ejb.SessionContext;
import javax.ejb.Stateless;
import javax.ejb.TimedObject;
import javax.ejb.TimerHandle;
import javax.ejb.TimerService;

@Stateless
public class EJBTimerBean implements EJBTimerLocal, TimedObject {
private SessionContext sc;
private TimerHandle timerHandle = null;

public void ejbTimeout(javax.ejb.Timer arg0) {
java.util.logging.Logger.getLogger(getClass().getName()).log(
      java.util.logging.Level.INFO,
      "CMS0000: EJBTimerBean: Tick");
}

public void ejbPostCreate() {
 // This does not work:
 Date now = new Date();
 initializeTimer(now, 30000, "CMS_TIMER");
}

public void initializeTimer(Date firstDate, long timeout, String timerName) {
try {
  TimerService ts = sc.getTimerService();
  Timer timer = ts.createTimer(firstDate, timeout, timerName);
  timerHandle = timer.getHandle();
  java.util.logging.Logger.getLogger(getClass().getName()).log(
      java.util.logging.Level.INFO,
      "Timer started.");
} catch (Exception e) {
  e.printStackTrace();
}
}

@Resource
public void setSessionContext(SessionContext ctx) {
sc = ctx;
}
}

Be sure the timer includes the setSessionContext() methods, with the @Resource annotation. Also, initializeTimer() must be declared in the bean's interface.

Here is the servlet, whose only purpose in life is to start the timer (note that some basic servlet code has been left out, it's not important for the example at hand).

package com.me.servlets;

import com.iwsinc.cms.ebj.EJBTimerBean;
import com.iwsinc.cms.ebj.EJBTimerLocal;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Date;
import javax.ejb.EJB;
import javax.servlet.ServletConfig;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class Watch extends HttpServlet {
@EJB
private EJBTimerLocal eJBTimerBean;

protected void processRequest(HttpServletRequest request, HttpServletResponse response)
   throws ServletException, IOException {
    }

public void init(ServletConfig config) throws ServletException {
super.init(config);
// Start the timer
// to-do: MAKE SURE only one timer is started!!
try {
   eJBTimerBean.initializeTimer(new Date(), 30000, "CMS_TIMER");
}
catch (Exception e) {
       java.util.logging.Logger.getLogger(getClass().getName()).log(
               java.util.logging.Level.SEVERE,
               "Exception", e);
       e.printStackTrace();  
}
}

public void contextInitialized(ServletContextEvent sce) {
}

public void contextDestroyed(ServletContextEvent sce) {
try {
   // to-do: Stop the timer
} catch (Exception e) {
   e.printStackTrace();
}
}
}

It took me awhile to figure out that to do this (this way), the EJB and the servlet must end up in the same ear file, that the annotation in the servlet for the EJB needs to be the interface, not the bean itself, and that the EJB needs to get its SessionContext using a @Resource annotated method, just as shown above.

On deployment of the web application, an exception is thrown by the EJB. The cause is not known at this time. i found a handful of questions on the various forums asking about this. This exception does not seem to impact the timer in anyway, as far as I can tell.

java.lang.IllegalArgumentException: "timers"
com.sun.enterprise.management.support.OldTypesBase.oldObjectNameToJ2EEType(OldTypesBase.java:153)
com.sun.enterprise.management.support.oldconfig.OldProps.(OldProps.java:187)
com.sun.enterprise.management.support.LoaderOfOldMonitor.oldToNewObjectName(LoaderOfOldMonitor.java:265)
com.sun.enterprise.management.support.LoaderOfOld.syncWithOld(LoaderOfOld.java:415)
com.sun.enterprise.management.support.Loader._sync(Loader.java:548)
com.sun.enterprise.management.support.Loader.sync(Loader.java:522)
com.sun.enterprise.management.support.Loader.handleMBeanRegistered(Loader.java:209)
com.sun.enterprise.management.support.LoaderRegThread.processRegistration(LoaderRegThread.java:204)
com.sun.enterprise.management.support.LoaderRegThread.process(LoaderRegThread.java:253)
com.sun.enterprise.management.support.LoaderRegThread.run(LoaderRegThread.java:154)