Custom Code - NetBeans Tutorial

From jVantage

In this tutorial we will add custom behavior to the sample Project Management application that ships with the jVantage development tool. First, we will create a custom EJB component that overrides and modifies the behavior of the Associate entity view within the application. With just a few lines of code we will display a message to the user on the user interface, insert some arbitrary data onto the user interface and access it via velocity, send an e-mail message with an attachment and finally insert some log entries into a log file. Once the code is written, we will define a trigger that tells jVantage when, where and how to execute code.

Contents 1 Create a NetBeans Project 1.1 Insert the jVantage Client JAR into Your Project 1.1.1 Unpack the jVantage Zip File 1.1.2 Create a lib Directory 2 Create a Stateless Session Bean 2.1 Add Custom Code 2.2 Promote the Method to the Remote Interface 2.3 Setting the JNDI Name of the EJB 3 Creating a Trigger

Create a NetBeans Project

After you have installed NetBeans, create a new project by selecting File > New Project > Enterprise > Enterprise Application. Populate the name and location dialog box as follows (you may choose a different location if you like).

Select Finished. NetBeans then creates the three primary project artifacts; the Application Module, the Web Module and the EJB Module. Your NetBeans project space should look similar to the following. Note that the Web module will be used in a later tutorial.

Most of the business logic that you write will execute either in the EJB container as an EJB component or an EIS component called from your EJB's. Although other call-out mechanisms may be introduced in future versions of jVantage, presently custom code is only accessed via calls to EJB components. The reason for this approach is that by utilizing the JNDI namespace to locate and execute methods on EJB components, jVantage preserves the complete decoupling of itself from any custom logic, and aside from the use of the PageContext object (and associated objects) that are part of the jVantage client JAR, this decoupling works both ways. This is one of the underlying premises of Service Oriented Architectures.

This approach of using EJB's for your business and custom code makes better use of the load-balancing and reuse capabilities of the J2EE platform than building applications that utilize only the Web container. Regardless of whether you use jVantage or not, taking full advantage of the application server during enterprise development is almost always a better approach than utilizing only the Web container. Many web frameworks utilize complicated and largely unnecessary external configuration files to accomplish the very things that the application server is already capable of doing far better if only used properly. Furthermore, the enormous number of difficult-to-maintain XML configuration files required by many Web frameworks can themselves become maintenance headaches.

Insert the jVantage Client JAR into Your Project

Unpack the jVantage Zip File

The jVantage ZIP file you downloaded contains a least two files. The first is the jVantage enterprise archive file, or EAR file. The second is a client JAR that is used for adding custom code to your jVantage applications. When you create a new project in the NetBeans IDE you must include the client JAR as a reference library so that you can interact with the jVantage API. As you'll see in the following sections, doing so requires almost trivial effort.

If you downloaded the jVantage release candidate one, you should have the following or similar file:

jvantage-ce-1.rc1.n.zip

Unpack this file into a temporary directory. You should see something similar to the following (this output reflects a Windows operating system, but the OS is irrelevant to the content).

 Volume in drive C is Local Disk
 Volume Serial Number is DCEC-8C7F

 Directory of C:\tmp\jVantageDownloadTmpDir

08/19/2006  07:33p      <DIR>          .
08/19/2006  07:33p      <DIR>          ..
08/19/2006  02:40p          14,267,383 jvantage-ce-1.rc1.1.ear
08/19/2006  02:40p             392,577 jvantage-ce-client-1.rc1.1.jar
               2 File(s)     14,659,960 bytes
               2 Dir(s)  46,693,408,768 bytes free

Notice that the client JAR is substantially smaller than the EAR file. The client jar contains only the information necessary to allow your custom code to know how to communicate with the jVantage API. It also contains utility classes and business objects that makes some functionality directly accessible within your custom code.

Create a lib Directory

The first thing we'll do is create a library directory within the EJB project and copy the jVantage client JAR to it.

C:\>cd C:\dev\NetBeansTutorial\NetBeansTutorial-ejb

C:\dev\NetBeansTutorial\NetBeansTutorial-ejb>mkdir lib

C:\dev\NetBeansTutorial\NetBeansTutorial-ejb>cd lib

C:\dev\NetBeansTutorial\NetBeansTutorial-ejb\lib>copy c:\tmp\jvantage-client-ce-1.rc1.1.jar .
        1 file(s) copied.

C:\dev\NetBeansTutorial\NetBeansTutorial-ejb\lib>dir
 Volume in drive C is Local Disk
 Volume Serial Number is DCEC-8C7F

 Directory of C:\dev\NetBeansTutorial\NetBeansTutorial-ejb\lib

09/09/2006  03:38p      <DIR>          .
09/09/2006  03:38p      <DIR>          ..
09/09/2006  08:53a             392,581 jvantage-client-ce-1.rc1.1.jar
               1 File(s)        392,581 bytes
               2 Dir(s)  47,808,901,120 bytes free

C:\dev\NetBeansTutorial\NetBeansTutorial-ejb\lib>

Next, we have to let NetBeans know where it is so it can be accessed and used from your project. From the NetBeans IDE choose File > Refresh All Files to cause the tool to notice the new directory. Then right click on the EJB project and choose properties from the pop-up menu. Select the libraries category then click on the Add JAR/Folder button and select the client jar from the library directory we created above. When finished, your properties dialog should look like the following.

Click OK to close the window.

Create a Stateless Session Bean

The next thing we'll do is create a Stateless EJB Session Bean where we will insert our business logic. Hopefully, we will accomplish a couple things in this section. One is to demonstrate how easy it is to insert custom code into jVantage applications. The second is to dispel the myth that working with EJB's is difficult. In the early days of the J2EE platform there were not many tools to aid in developing EJB's, however, modern IDE's such as NetBeans are now available that allow EJB's to be created with minimal effort -- as we're about to see.

To create the bean, simply right-click on the EJB project and select New | Session Bean from the pop-up menu.

Populate the form as show here and select Finish. Be sure to check the Create Interface: Remote box.

Add Custom Code

Insert the following method into the EJB class that was generated by NetBeans.

    public SnapInResponse execute(PageContext pageContext) throws SnapInException {

        //  Get a SnapInResponse instance from the pageContext.
        SnapInResponse siResponse = pageContext.getSnapInResponse();

        try {
            //======================================================================//
            //  Report errors to users on the user interface.
            //======================================================================//
            //  Causes an error message box to display on the user interface.
            siResponse.addUserErrorMessage("This is my test error message");

            //  Causes an informational message box to display on the user interface.
            //  If and error has also been added (siResponse.addUserErrorMessage(...)),
            //  then the informational message(s) will be displayed in the same box
            //  as the errors.
            siResponse.addUserInfoMessage("This is my test info message");

            //======================================================================//
            //  Add custom content to the user interface using label/value pairs.
            //======================================================================//
            //  Adds a value to the Velocity context, making it available on the
            //  user interface.  To access the value, simply add the variable ${MyTestTag}
            //  to the HTML (or XML) template. The value 'This is my test tag value.' will
            //  then be inserted into the user interface in its place.
            siResponse.setTagValue("MyTestTag", "This is my test tag value.  Set from the NetBeans tutorial.");

            //======================================================================//
            //  Override entity attributes for display purposes.
            //======================================================================//
            //  If there is an attribute called firstName associated with the entity being
            //  displayed in the current context, this will override its display label.
            siResponse.setAttributeDisplayLabel("firstName", "My First Name");

            //  If there is an attribute called firstName associated with the entity being
            //  displayed in the current context, this will override its value.  Note that
            //  this only overrides the value that is going to be displayed to the user, it
            //  does not change the persisted value.
            siResponse.setAttributeValue("firstName", "George");

            //======================================================================//
            //  Send email messages
            //======================================================================//
            //  Add zero or more email messages to the reponse and jVantage will automatically
            //  send them.  There is no need to bind to, or know anything about the details of
            //  the email subsystem.
            EmailMessage emailMessage = new EmailMessage();
            emailMessage.addToAddress("email.recipient@someorganization.org");
            emailMessage.setSubject("Test Email from jVantage SnapIn Tutorial");
            emailMessage.setContent("This is my test content.");
            
            //  Add an attachment.
            EmailAttachment emailAttachment = new EmailAttachment();
            emailAttachment.setDescription("Test attachment.");
            emailAttachment.setName("AttachmentName");
            emailAttachment.setPath("C:/jvantage/test.file.name");
            
            //  Set the email disposition as follows:
            //
            //      emailAttachment.setDisposition(EmailAttachment.ATTACHMENT);
            //
            //  - or -
            //
            //      emailAttachment.setDisposition(EmailAttachment.INLINE);
            //
            //  The default is EmailAttachment.ATTACHMENT, so there is no need
            //  to set it explicitly here.
            
            //  Add the attachment to the EmailMessage.
            emailMessage.addAttachment(emailAttachment);
            
            //  Add the emailMessage to the response.  jVantage will handle the rest.
            siResponse.addEmailMessage(emailMessage);
            
            //======================================================================//
            //  Log 
            //======================================================================//
            //  Writes the argument String to the SnapIn log as an error.
            siResponse.logError("This is a snapIn error log entry.");

            //  Writes the argument String to the SnapIn log as a warning.
            siResponse.logWarn("This is a snapIn warn log entry.");

            //  Writes the argument String to the SnapIn log as an information entry.
            siResponse.logInfo("This is a snapIn info log entry.  Set from the NetBeans tutorial.");

            //  Writes the argument String to the SnapIn log as a debug message.
            siResponse.logDebug("This is a snapIn debug log entry.  Set from the NetBeans tutorial.");
        } catch (Exception e) {
            throw new SnapInException("Exception", e);
        }

        //  Return the response.
        return siResponse;
    }

After this method is been inserted into the class and saved, NetBeans will display several errors that indicate that many of the object types used in this method are not recognized. Select Alt-Shift-F to cause NetBeans to automatically attempt to discover and insert required imports.

If a window similar to the one above appears, it means that NetBeans found another class called PageContext and it doesn't know which one to use. Be sure to select the jVantage PageContext class from the Fully Qualified Name list and click OK. All errors should now be resolved.

Promote the Method to the Remote Interface

Next, we need to expose our custom method on the EJB remote interface. This will make the method accessible to calls from outside of the immediate EJB container instance (or server instance) that it is installed in. Do this by right-clicking on the method signature and selecting EJB Methods | Add to Remote Interface as shown below. The remote interface will be used to access this method from within the jVantage application.

Setting the JNDI Name of the EJB

Now we will set the JNDI name for the EJB so that it can be accessed dynamically from within jVantage. An interesting thing to point out about this step is that jVantage has no compile-time knowledge of the EJB that we just created or, as a matter of fact, our project. In a little while we will create a trigger that instructs jVantage to call out to this EJB and execute our custom method without requiring any changes to the jVantage instance. In fact, jVantage will not even have to be restarted. All that will be required is a refresh of the jVantage development environment. After our custom component is deployed on application server, jVantage will simply call it directly. This kind of hot-swapping ability brings flexibility and the promise of the loose coupling of business components into full view.

Creating a Trigger

Triggers are mechanisms for telling jVantage to perform various tasks. When you write custom code, a trigger is needed to tell jVantage when and how to call that custom code.