MDK Development Cycle  |   MDK Wizard Configuration  |  Import a .war file into a new project  |  New MI project

 

Export a Project into a .war File

To activate this function select following commands from the Eclipse menu: File > Export > MDK: Export project into web archive (.war)

This function creates a .war file of your Eclipse project. First you will be asked which project you want to export. Only "MDK projects" are displayed. In case your project does not show up, you have to create a "New MI project" and import the sources with the standard Eclipse commands. After you select a project the export dialog window, depending on your application type (JSP or AWT) is displayed.

The archive must have the name as the application. The application name is defined in 'getApplicationName' method of your implementation of the AbstractMEHttpServlet or AwtApplication. The application name must not exceed 30 characters. In case you select a archive file name that has more than 30 characters, the dialog window displays a message:

 

Case 1. AWT application:

 

Case 2. JSP Application with disabled JSP compilation option:

 

Case 3. JSP Application with enabled JSP compilation option:

  1. MI appplication name: (.war) or (.jar): The name of the .war-file (JSP application) or .jar file (AWT application) in which the selected project is exported.
    The .war-file/.jar-file name has to match the name of the application that you defined in the getApplicationName() method. If you define the application name by using the MI_APPLICATION_NAME String variable the plug-in uses the correct .war/.jar file name automatically. You can define the MI_APPLICATION_NAME String variable in any .java file the belongs to that project. The MI application name may not contain special characters, like *.-& and so on. If the archive name contains such a character, an information is displayed on top of the dialog window and the Finish button is not enabled.
    Example:
    Case 1 shows the dialog window, when no MI_APPLICATION_NAME String variable is defined. In this case, you have to specify the application name manually.
    Case 2 and 3 show the dialog window, when the MI_APPLICATION_NAME String variable is defined. In this case, you cannot specify the application name manually.

  2. MI appplication folder :You can specify disk drive and folder or use the ... button to browse through the file system. The default folder for JSP applications is the webapps folder of the Mobile Infrastructure Tomcat installation. The default folder for AWT applications is the lib folder of the Mobile Infrastructure installation.

    When you export one project under different .war file names you create different web applications. The Mobile Infrastructure class loader however traces all web applications to find start a class, regardless of the web application name. Therefore it is important to deploy applications that have unique class names (package + class name).



  3. Include the source code of the project: When this option is enabled the MDK export function will package all .java files into a application_name.src.zip file in the folder WEB-INF/srclib. When you import a .war file with sources included you instantly have a project you can modify and deploy again.

    JSP applications only:
  4. Add JSP as compiled classes: When this option is enabled the MDK export function will compile all JSP in your application and add the class files to the .war file. No JSP are deployed. In addition the web.xml file is updated, so that the compiled JSP servlet names are included.
    When this option is enabled, the dialog window shows two additional radio buttons (see picture for "Case 3" above).
    1. Delete generated Java files after .war file has been generated:
      Default. The MDK Plug-in keeps the generated Java files from the JSP compilation temporarily and deletes the Java files after the .war file has been generated. You will see no change of your project in the Java Browser of Eclipse.
    2. Keep generated Java files in project after .war file has been generated:
      The MDK Plug-in keeps the generated Java files from the JSP compilation. You will see the change of your project in the Java Browser of Eclipse. You will find an additional source folder, called $JSP, in you project, that contains the Java files. A regular folder, called $WEB, contains a copy of your original web.xml file. In order to work with the generated Java files, the web.xml file in the WEB-INF folder contains the additional entries of the Java classed that come from the JSP compilation. We recommend, not to delete the $WEB folder. The MDK Plug-in refers to the web.xml copy in this folder whenever you repeat the export function.
      When you keep the Java files, you can debug the JSP from Eclipse. See, Tips and Tricks for more details.

    When a .war file has to be deployed on a device that has only a Java Runtime (JRE) installed, you have to create the .war file with compiled JSP. JSP compilation by the Tomcat servlet engine requires the Java Development Kit (JDK).

    We strongly recommend to use the Java files in the $JSP source folder only temporarily and for debugging purposes only. When you have found the bug in your JSP, make the changes in the JSP and than export the project again with the "Add JSP as compiled classes" option enabled. Never change the Java files in the $JSP source folder.
    Because of the temporarily use of the Java files we do not organize the imports and format the source code of the Java files in the $JSP folder. This leads to some warning icon in the $JSP folder indicating unused import statements. The warning icons do not cause any harm and should remind you, that these files are only temporarily.

    Adjustments in the web.xml file:
    MI JSP applications should usually use a servlet that implements mehttpservlet. This servlet then calls the JSP. The entry in the web.xml for the /start URL pattern refers to the implemented mehttpservlet class. This class name stays the same, regardless if you use JSP or compiled JSP.
    If an MI JSP application starts a JSP first, you have to adjust manually the /start URL pattern if use .JSP ( the /start URL pattern has to refer to the JSP file) or compiled JSP ( the /start URL pattern has to refer to the compiled class).


  5. Run the mobile application: When this option is enabled the MDK export function will start the Tomcat servlet engine to deploy the generated .war file and launch the browser to run the mobile application. In case the Tomcat servlet engine does not come up or the browser is not launched refer to the MDK plug-in configuration description and check your configuration.

  6. All mobile applications need to be deployed at least once via the MI Web Console before being started via this feature. Only when deployed via the MI Web Console, a mobile application is properly registered with the MI framework and can then use framework services. Please read the instructions in chapter 'Software Logistics -> Deployment during Development' in the MDK documentation carefully.

    If it is a new mobile application you are deploying, the Run the mobile application option is disabled. A text line under the check box displays a message that the application has to be deployed via the MI Web Console. The MI Web Console is started by the export function when you choose Finish (the MI Client Installation has to be configured correctly, for example, port number and server name, to allow the export function to start the Web Console).

    If the MI runtime does not match the archive, for example. you are trying to export a .war file but the MI runtime is configured for AWT, the check box to run the mobile application is disabled.



  7. URL pattern to start application: The URL pattern has to match the entry in the web.xml file. The URL pattern defines the class that is called when the application is called via the URL.
    Example:
    web.xml for EXAMPLE.war
    
    
    
    <web-app>
      <servlet-mapping>
       <servlet-name>Example1</servlet-name>
       <url-pattern>/start</url-pattern>
      </servlet-mapping>
      <servlet>
       <servlet-name>Example1</servlet-name>
       <servlet-class>example1Servlet</servlet-class>
      </servlet>
    </web-app>
    
    This entries define, that the class example1Servlet is called when the mobile application is started with the URL:
         http://localhost:4444/EXAMPLE1/start

  8. Uppercase for .war file name: Mobile application should always be named in uppercase characters to avoid naming clashes with the server. When this option is enabled, the MDK plug-in generates .war files in uppercase characters - regardless of the .war file name specified.

  9. Start MI Homepage when browser is launched: When this option is enabled, your application is deployed and the web browser comes up with the Mobile Engine login screen or, if you provided a password in the MDK plug-in configuration, the MI homepage. This option allows you to test your application started from the MI homepage.

 

In order to be compatible with PDAs your mobile application should be built with Java Version 1.1.8. You can select the Java version which is used for building with the Eclipse commands:

Window > Preferences > Java > Installed JREs


The export function of the MDK Plug-in also creates a "Launch Configuration" in Eclipse under the launch configuration group "MI Application". You have access to the "Launch Configuration" by using the Eclipse commands Run > Run ... or Run > Debug.... The "Launch Configuration" has the name if the project and give you the opportunity to start your application manually. See, Tips and Tricks for more details.

 

Directory structure Eclipse versus .war File

Eclipse Project Folder Structure

Eclipse project folder structure of a mobile application:

java
A package folder that will contain the source code of the application. The source code is extracted from the .war file folder WEB-INF/srclib/application_name.src.zip.

app-root
A folder that contains the "root" folder of the .war file. In the "app-root" folder you will find the folders "META-INF", "WEB-INF" etc..

 

.war File Folder Structure

When you export a project into a .war file it has following folders:

Eclipse folder

.war file folder
/java /... All .java files are packaged and saved as WEB-INF/srclib/WARFileName.src.zip.
Resource bundles (.properties) are packaged in the .jar file in the WEB-INF/lib folder of the .war file.
/app-root /... All folders under app-root are placed in the root folder of the .war file. For example, Eclipse project folder /app-root/WEB-INF becomes WEB-INF in the .war file.

Problems in Development Cycle

When you create a .war file and start Tomcat the files in the .war file are deployed. JSP are "precompiled" by Tomcat into .java files when called the first time. The Java compiler is started and creates the final class file of the JSP servlet and your application is displayed in your web browser. The "compilation" process takes place in the work folder of Tomcat which is located in <ME_HOME>/work.

When you deploy the application frequently during testing time it can happen, that the latest JSP you deployed is not "precompiled" by Tomcat and an older "precompiled" version is used - so your changes would not be visible. In this case delete all application-context-specific folders in folder <ME_HOME>/work and start again.

 
Error during Export in Eclipse:

It can happen, that the you get an exception during the export function, that indicates that resource cannot be deleted. This error occurs when Eclipse cannot clean the output folder. Eclipse cleans the output folder (usually folder WEB-INF/classes) before it recompiles the project. For an unknown reason so far, the .class files are locked by the Java VM and Eclipse cannot delete the files. Right now the only thing we can recommend is:

Close the project and open the project again. To do that, click on the project with the right mouse button and select "Close Project" from the context menu. To open the project, click on the project with the right mouse key again and select "Open Project" from the context menu. You have to rebuild the Project (Eclipse command: Project > Rebuild Project) to get rid of the error sign in front of the project.

If there are still problems you have to restart Eclipse (Closing Eclipse and start it again).