Setting up the IDE

UltraESB is an ESB with seamless IDE integration, facilitating development, running/testing and debugging of the mediation flows within the IDE itself to improve the development life-cycle of your integration project.

Usage of IDE reduces the development time and improves the quality
Usage of the IDE reduces the UltraESB mediation solution development time drastically. It speeds up and improve the quality of all the 3 faces of the life-cycle;
1. Development - Auto completion and context sensitive information guides you develop the solution faster
2. Running/Testing - No need to build and deploy, you can run the solution that you just coded within the IDE, just like a standalone application and test it
3. Debugging - Just debug instead of running and step through within the IDE to find the cause of the problem or to evaluate any expressions

UltraESB supports all 3 major Development Environments and the following sections will discuss setting up the respective IDE to develop, run and debug UltraESB.

IntelliJ IDEA - Setting up IntelliJ IDEA
Eclipse - Setting up Eclipse
NetBeans - Setting up NetBeans

At the end of this section, you have mastered the IDE of your interest to develop, run and debug the UltraESB mediation flows.

Setting up IntelliJ IDEA

This guide introduces the user to the UltraESB configuration, testing and debugging with the IntelliJ IDEA Community Edition, which is an excellent IDE now available free of charge - which offers intelligent editing of the configuration as well as editing of Java code fragments embedded within the XML configuration elements.

The UltraESB distribution ships with an IntelliJ IDEA project that allows one to edit the configuration, write custom mediation code, test mediation and services, and debug everything from within the excellent and user friendly IDE environment. You could easily create a similar project for your favourite IDE, and share it with AdroitLogic for inclusion into future releases. Opening the UltraRuntime project at the UltraESB home directory, one could now start to edit the configuration as shown below from within the IDE.

The very first time IDEA opens up the configuration file, if it reports that the schema URI’s are not registered, hover the mouse over the highlighted text and then when a balloon to the left edge of that line pops up, clinking that will show a menu to "Fetch External Resource". You will need to be connected to the Internet, and once you fetch all highlighted schemas you are all set to use the smart schema aware editing features of the IDE.

Note that as the UltraESB configuration is a Spring XML configuration file, a Spring aware version of IntelliJ IDEA (i.e. the commercial version) or another IDE that supports intelligent editing of a Spring configuration will be able to prompt with the valid options for configuration of the Spring managed beans as shown below. This applies when configuring the transports, transaction and JNDI settings etc.

When editing the mediation aspects of the UltraESB (e.g. ultra-unit.xml of a deployment unit), any schema aware IDE or editor will now be able to prompt the possible and valid options as per the public schema, and report any violations etc. as shown below. Note that the community edition of the IntelliJ IDEA IDE includes this support.

The IntelliJ IDEA IDE community edition also has support for language injection, which could be used to edit Java mediation fragments within the XML configuration.

To enable this feature, open "Settings" and select "Editor" and then "Language Injection" (on IDEA 10.x and earlier versions this is available under "IDE Settings"), and add a new language injection for the XML element from the context menu as shown below.

Note
Before you start working with language injections, make sure that IntelliLang plugin is enabled.

You will need to specify the following text as the prefix, and then specify the string "}}" as the suffix to allow us to just write a Java code fragment without writing a full Java class within the configuration.

Prefix

import org.adroitlogic.ultraesb.api.*;
class x {
    private static final org.adroitlogic.logging.api.Logger logger = org.adroitlogic.logging.api.LoggerFactory.getLogger("sequence");
    public void execute(Message msg, Mediation mediation) throws Exception {

Suffix

}}

The prefix will also import the public API and expose the current message as a variable named "msg". The IDE will not inject this prefix or suffix into the configuration, but the user must ensure that any code fragment is a valid xs:string schema data type. Its always suggested to wrap code fragments within "<![CDATA[" and "]]>" tags to ensure that the content is properly handled by the XML parser.

Then fill the "XML Tag" section with local name "java" under the namespace "http://www.adroitlogic.org/ultraesb" as shown below.

Once the language injection is configured, the IDE will allow one to edit the Java code fragments within the XML configuration with full IDE support as shown below.

The UltraRuntime project ships with a configuration to start the UltraESB from within the IDE both in normal execution mode, and in debug mode. The same would be easily possible with any other IDE. This allows one to edit the configuration, run and debug the configuration all from within the same IDE environment.

If you see the following red coloured (X) sign in the runtime configuration as shown below marked as (1), that means the JDK is not configured properly for the project.

If this is the case, you need to configure the JDK for your project. For that matter, click on the Project Structure as shown by (2) or press the short cut key combination Ctrl+Alt+Shift+S to edit the project structure.

Specify a new JDK following the steps;

Click on the Modules under Project Settings from the left most column to select the "UltraRuntime" module settings
Select the Dependencies tab
Click on the New button to define a new JDK as the Module SDK.

You will be able to see the following options drop down and select the JDK for the module SDK.

Now you will be able to see the following screen to setup the JDK as follows.

Select the JDK installation directory and click OK as shown in the actions (1) and (2). Click OK for all the open windows to confirm your action to setup the JDK properly.

Setting up support for JSR 223 Scripting Languages - e.g. Groovy

The IntelliJ IDEA CE has built-in support for Groovy. To enable auto completion and full IDE support, first download Groovy and setup the IDEA project to use / support Groovy. In your Groovy script used for mediation, include the following snippet at the top

Groovy header

import org.adroitlogic.ultraesb.api.Mediation import org.adroitlogic.logging.api.Logger import org.adroitlogic.ultraesb.api.Message Mediation mediation = mediation; Message msg = message; Logger logger = logger;

The IDE will support autocompletion and other advanced options now as follows

Congratulations!! You and your IDE is now ready to start the development, running, testing and debugging of your UltraESB integration solution!

Setting up Eclipse

This guide describes the steps taken to setup the Eclipse IDE to configure, run/test and debug UltraESB mediation solutions. We have used the "Eclipse IDE for Java EE Developers" release Luna (4.4) for this exercise.

To get started with, start the Eclipse IDE and open an existing workspace or select a new workspace (e.g. C:\Users\asankha\workspace). If you are already on the Eclipse Workbench, select File → Switch workspace and select the workspace or select "Other" to specify a new workspace.

Select File → Import and from the pop-up window, select General → Existing Projects into Workspace, and specify the path to the UltraESB installation (e.g. C:\With Space\ultraesb-2.6.1)

You may now see 2 Problems reported against the project for its Java Build Path. This is due to a known issue with Eclipse, as the path to the tools.jar of the JDK cannot be detected automatically [MECLIPSE-253].

Right click the error line "Unbounded classpath variable 'JAVA_HOME' …" and select 'Quick Fix' from the popup menu. Press the 'Finish' button.

Then from the 'Libraries' tab, select 'JAVA_HOME' and press 'Edit', next select 'Variable' from the 'Edit classpath variable entry' and define a new variable 'JAVA_HOME' pointing to the JDK home (e.g. /opt/jdk1.7.0_80). Confirm request for a full build, and the Problems would disappear from Eclipse.

Run configurations are automatically created for Eclipse for the following:

UltraESB - default configuration
UltraESB Sample - edit sample configuration as required
UTerm
SOA ToolBox

The above Run configurations can be found under 'Java application' category for 'Run configurations' and could be used to run / debug each of the above from within the Eclipse IDE.

To create a Run configuration to run or debug the UltraESB from within the Eclipse IDE, go to Run → Run Configurations. Create a new 'Java Application' configuration selecting the project as 'UltraRuntime' and the main class as 'org.adroitlogic.ultraesb.UltraServer'. Specify '–confDir=conf' as program arguments, and '-Djava.endorsed.dirs=lib/endorsed' as VM arguments. This creates an Eclipse run configuration to start/debug the default UltraESB configuration as defined in the conf/ultra-root.xml and conf/ultra-dynamic.xml.

To configure specific samples to be run from within Eclipse, select the run configuration 'UltraESB Sample' and edit its 'Arguments' to pass the required configuration file from the samples. (e.g. –confDir=conf –rootConf=samples/conf/ultra-sample-101.xml)

To run any of the unit tests supplied, select the test case and run as a JUnit test case

Note
To setup XML file editing with schema based auto-completion etc, refer to standard Eclipse documentation and extensions.

Congratulations!! You and your IDE is now ready to start the development, running, testing and debugging of your UltraESB integration solution!

Setting up NetBeans

This guide describes the steps to be taken to setup the NetBeans IDE to configure, run/test and debug UltraESB mediation solutions. We have used the NetBeans 8.0 for this exercise.

To get started with, start the NetBeans IDE and navigate to File→Open Project

Next, navigate to the UltraESB installation directory where a pre-configured project file exists

NetBeans will then scan the project folder and open the project on the IDE. You might see a warning "Reference Problems" as shown below.

If you click resolve problems, you will be redirected to another window as the following. This is due to some JAR files are which are not bundled with UltraESB are required for certain sample cases. You can simply ignore them.

Once the project opens, you could switch to the "Files" view from the left navigation panel, and then select the conf/deployments/default/ultra-unit.xml for example to edit. Notice that the UltraESB schema will be automatically retrieved, and auto-completion support will be enabled. (e.g. type "<u:" above the <u:inDestination> element)

To debug/run the default configuration, un-comment the inSequence definition in "echo-proxy" proxy in the conf/deployments/default/ultra-unit.xml to read as follows:

<u:inSequence>
    <u:class name="sample.SimpleJavaMediation1"/>
</u:inSequence>

Next navigate to UltraRuntime/conf/mediation/src/java/sample/SampleMediation1, and place a break-point at the System.out.println() line of the execute() method

You could not debug the default configuration named as "UltraESB". To debug a sample configuration, customize the "UltraESB Sample" profile

If you use the ToolBox to start the sample Jetty Server, and issue a HTTP request using prefix #1, you would endup in the debugging view at the breakpoint

Note that you can evaluate variables and perform other typical debugger tasks while the message is live within the ESB

To debug a sample configuration, customize the "UltraESB Sample" profile as follows, and specify the sample configuration file. The line would read as follows by default:

--confDir=conf --rootConf=samples/conf/ultra-sample-101.xml

To run/debug sample 201, you should update the –rootConf parameter accordingly.

JSR 223 scripting language setup
For information on setting up NetBeans for use with Groovy or other JSR 223 scripting languages, refer to the NetBeans documentation.

Congratulations!! You and your IDE is now ready to start the development, running, testing and debugging of your UltraESB integration solution!