Build environment

Creating a Nexaweb Application requires that the developer create:

• XML files that define the User Interface (UI) layout
• Java or JavaScript files for Managed Client Objects (MCO), JavaServer Pages (JSP) and Servlets

To do this, you need, at a minimum, an editor and Java compiler. Most developers these days use some form of Integrated Development Environment (IDE), which provides additional tools to make the developer more productive. For example, Nexaweb also provides an IDE called Nexaweb Studio that provides tools to graphically create Nexaweb UI XML files. Many software projects use an automated command-line build tool to facilitate routine builds, and Apache Ant has become a de facto standard for these types of systems. Ant is also used by developers who prefer to use "plain" text editors such as Emacs, VI, or Notepad. This document will discuss the steps required to build a typical Nexaweb application with both Ant and Nexaweb Studio.

This document assumes that the reader already understands how to use Ant. If not, the reader should go to their web sites,Apache Ant - http://ant.apache.org/, for more information. This site provides a good tutorial within their documentation for both new and advanced users.

 Note: Nexaweb-enabled applications may be deployed on any Servlet container that conforms to the Servlet 2.3 (or later) specification, including Apache Tomcat and J2EE application servers.

A Nexaweb-enabled application is deployed as a standard J2EE web application, with some additional Nexaweb resources.  A typcial web application looks as follows:

The public web resources (for example,  HTML files) are stored in the top level directory, and other directories except for WEB-INF. WEB-INF is a special directory whose contents are hidden from external users. This directory contains web application private resources and configuration information such as the Java classes for servlets (stored in WEB-INF/classes) and Java library files (stored in WEB-INF/lib). WEB-INF/web.xml is THE configuration file for the web application that contains information about servlets to load, URL mappings, and other resources.
A Nexaweb-enabled application has the exact same structure with some additional resources.

To add Nexaweb Platform to a new or existing web application, you follow thes same basic steps; however, for an existing application, you must  take care of the following existing files before adding Nexaweb Platform to the application:

• index.jsp - Nexaweb uses this file to launch the Nexaweb client code within the user’s web browser. If your project already has an index.jsp, you’ll need to copy nexaweb-platform.zip’s index.jsp to a different file, and call it from the web browser when you are ready to start Nexaweb.
• WEB-INF/web.xml  - The nexaweb-platform.zip file merges additional items into your existing project’s WEB-INF/web.xml file. These extra entries define and configure Nexaweb Servlets that must exist within your web applications for Nexaweb to function properly.

To add Nexaweb Platform to a new or existing web application, follow these steps:

1. Create a new project directory (for example, mywebapp).
2. Unzip <nexaweb install>/dist/nexaweb-platform.zip into that directory

Now you can start creating XAL files for UI, and JSP and Servlets using your existing XML and Java/J2EE tools.

An even simpler way to get started is to leverage the existing samples provided with Nexaweb, their Apache ANT build files and the ‘nexawebify’ task.

Using ANT to build Nexaweb-enabled applications

All of the samples provided with Nexaweb include an Apache ANT build file and Nexaweb Studio project files. Using one of these samples as a starting point for your Nexaweb-enabled application will save you a great deal of time as you will start with a best practices project already configured.

Although most of the declarations and instructions in build.xml are typical of any script used to build a Web application, one instruction is unique to the Nexaweb Platform: nexawebify. This instruction runs a program in nexaweb-platform-installer.jar (found in the bin folder of the Nexaweb Platform installation), which in turn collects components from nexaweb-platform.zip (found in the dist folder of the Nexaweb Platform installation) to make the Nexaweb Platform class libraries, JSP pages, and default images for Nexaweb Platform components available to the application at runtime. As part of this process, the nexawebify instruction modifies WEB_INF/web.xml to include references to the Nexaweb Platform components. Finally, nexawebify creates the file, index.jsp, which will be used to launch your application when invoked by a browser request.

To use existing build files, follow these steps:

1. Copy the build.xml and build.properties files from the root directory of an existing project into the root directory of the current project.
2. Edit the build.xml file to specify the current project name at the top of the file.
3. Edit the build.properties file to specify the Nexaweb home directory on this system.

You can use ANT to build the project from Nexaweb Studio or at the command line.

Using Nexaweb Studio

To use Nexaweb Studio to build the project, follow these steps:

1. In the Java Perspective, select Show View > Other > ANT.
   The ANT view opens at the bottom of the workbench.
2. Drag the build.xml file for this project into the ANT view.
   The ANT view displays a list of the projects you can build.
3. Double click on dist, to build the project.
   A WAR file appears in this project's  /dist directory.

Using the Command Line

1. At a command prompt, navigate to the root directory of the project that you want to build.
2. In an MS-Windows environment, type: %ANT_HOME%\bin\ant.ext build.xml and press the Enter key.
   A WAR file appears in this project's /dist directory.

Procedure for deploying the application to your Servlet container