OMS with Web Start. Deploying Open ModelSphere as Web Start Application. Marco Savard, neosapiens

Transcription

1 OMS with Web Start Deploying Open ModelSphere as Web Start Application Marco Savard, neosapiens August 2010

2 TABLE OF CONTENTS Chapter 1 - Introduction...1 Chapter 2 - Using NetBeans Installing NetBeans Creating OMS Projects in NetBeans The jack project settings The sms project settings Running the application (locally) Running the application (remotely)...7 Chapter 3 - Outside NetBeans Running Open ModelSphere from a Web Browser Structure of a JNLP file...8 Chapter 4 - Deploying on a Web Server Deploying Open ModelSphere on the Kenai server Deploying Open ModelSphere on your own web server...11 Chapter 5 - Troubleshooting Building the application Launching the application Running the application...14 Chapter 6 - Conclusion Prefer user.home over user.dir system property Remove accentuated characters in Java code Do not rely on the class loading order String initialization...17 Appendix - Acronyms...18 References...19 Index...20 i

3 TABLE OF FIGURES Figure 1: OMS Project Structure...3 Figure 2: Jack Project Properties...4 Figure 3: Sms Project Properties...6 Figure 4: Project Properties for a Remote Deployment...7 Figure 6: File content of a Kenai project...10 Figure 7: Association between Programs and File Extensions...12 Figure 8: Sms Project Properties...13 ii

4 LIST OF TABLES Table 1: Structure of a JNLP file...9 Table 2: Java system properties (assuming Admin is the current user)...16 iii

5 CHAPTER 1 - INTRODUCTION Abstract: This document explains how to get sources of Open ModelSphere (OMS), deploy the application as a Web Start application. At the end, we should be able to start OMS remotely from a web browser. 1

6 CHAPTER 2 - USING NETBEANS 1 Installing NetBeans It is recommended to use NetBeans because this IDE has built-in WebStart deployment facilities. In this document, NetBeans 6.7 (RC3, 264 MB) has been used and the examples have been tested with this version. Go to the NetBeans' download page (netbeans.org/downloads/index.html) and download this version. You could use the latest version of NetBeans (IDE 6.9.1, 214 MB was the current version when this document was written), but versions after NetBeans 6.7 have not been tested and may not work.\ 2 Creating OMS Projects in NetBeans Create the OpenModelSphere project in NetBeans (File New Project..), in Categories, select Java and press Next. Enter OpenModelSphere as Project Name and press Finish. Get the code source from JavaForge and copy it in the src/ folder. Copy also the libraries (.jar files) in the project. The project structure in NetBeans should look as illustrated in the figure below. Note that: Libraries refered in the jack project (jazzy, jython) must also be refered in the sms project. The library org.modelsphere.jack.jar, generated by the jack project, must be refered in the sms project. Chapter 2 - Using NetBeans 2

7 Figure 1: OMS Project Structure 2.1 The jack project settings The following screenshots are the properties related to the jack project. Right-click the org.modelsphere.jack node in the NetBeans' explorer, and choose Properties in the pop-up menu. Chapter 2 - Using NetBeans 3

8 Figure 2: Jack Project Properties Note: do not enable Web Start for the jack project. Chapter 2 - Using NetBeans 4

9 2.2 The sms project settings Note: Add org.modelsphere.jack.jar in the list of Libraries. Chapter 2 - Using NetBeans 5

10 Figure 3: Sms Project Properties Note: the Arguments and VM Options specified here will be generated in the.jnlp file. Chapter 2 - Using NetBeans 6

11 Note: Run and test locally (Codebase=Local Execution) before trying it in a remote site. 2.3 Running the application (locally) Find Application.java (in org.modelsphere.sms), and Select "Run File". The application should start. 2.4 Running the application (remotely) Create an account on a web server that supports Web Start. Change Codebase to User defined and enter URL address. For further details, read "Enable Java Web Start in the NetBeans IDE". at netbeans.org/kb/docs/java/javase-jws.html. Figure 4: Project Properties for a Remote Deployment Chapter 2 - Using NetBeans 7

12 CHAPTER 3 - OUTSIDE NETBEANS In the previous chapter, you have packaged OMS files within NetBeans. 1 Running Open ModelSphere from a Web Browser You could also test it outside NetBeans. In Windows Explorer, explore the generated files. In the dist/ folder, double-click the launch.html file. The application should start. Figure 5: Files Generated by NetBeans 2 Structure of a JNLP file A JNLP file contains the information required to launch a Web Start application. It is similar to a.bat file in functionality, but has an XML structure. The structure of a.jnlp could look like: <?xml version="1.0" encoding="utf-8" standalone="no"?> <jnlp codebase=" spec="1.0+"> <information> <title>silverrun Viewer</title> <vendor>grandite</vendor> <homepage href=""/> <description>org.modelsphere.sms</description> <description kind="short">org.modelsphere.sms</description> <offline-allowed/> </information> <security> <all-permissions/> </security> Chapter 3 - Outside NetBeans 8

13 <resources> <j2se version="1.6+" java-vm-args="-xss16m -Xms32m -Xmx1024m"/> <jar eager="true" href="org.modelsphere.sms.jar" main="true"/> <jar href="lib/jgrapht-all.jar"/> <jar href="lib/jython.jar"/> <jar href="lib/jazzy-core.jar"/> <jar href="lib/jakarta-regexp-1.5.jar"/> <jar href="lib/lablib-checkboxtree jar"/> <jar href="lib/org.modelsphere.jack.jar"/> </resources> <application-desc main-class="org.modelsphere.sms.application"> <argument>-pluginpath= </application-desc> </jnlp> Table 1: Structure of a JNLP file Note: the terminal '/' in <argument>-pluginpath=.. is important, do not remove it. Chapter 3 - Outside NetBeans 9

14 CHAPTER 4 - DEPLOYING ON A WEB SERVER Once the application can be launched locally, the next step is to launch it on a web server. The hosting web server must be able to launch Web Start applications. The Kenai (kenai.com) web server is a good host to test your application, because it supports Web Start by default, you can create an account without fees, and it is integrated with the NetBeans IDE. 1 Deploying Open ModelSphere on the Kenai server Create a free account and a project on Kenai. Then, upload the contents of the dist/ folder on your local machine to the project you have created. At the end, you should see the following files. Figure 6: File content of a Kenai project To launch the application, you can: click the link associated to the launch.jnlp (or launch.html) file in your Kenai, as shown in the screenshot above. or enter <PROJECT> being the name of your Kenai project, in the address box of your web browser. For further details on the Kenai web server, consult the following online document: Chapter 4 - Deploying on a Web Server 10

15 2 Deploying Open ModelSphere on your own web server Deploying Open ModelSphere on your own web server should not be different that deploying it on the Kenai web server. It should work whether the server is an Apache or an IIS web server. It is not required to have a full JRE (Java Runtime Environment) installed on the web server; JRE is required only on the client side, where the Java application actually runs. However, the web server must be configured to launch Java Web Start when.jnlp file are invoked. This is done by associating the.jnlp file extension to the Java Web Start Launcher application in the MIME types. The way to associate.jnlp file with Java Web Start Launcher may depend of the kind of web server you are using. In general, you should have a web.xml file in which insert a <mime-mapping> clause. Consult the online document Setting Up a Web Server1. If you are using Tomcat, the following link may be useful: If you are using cpanel to configure your web server, the following link may be useful: Chapter 4 - Deploying on a Web Server 11

16 CHAPTER 5 - TROUBLESHOOTING 1 Building the application Problem: When I compile the project, I get "unmappable character for encoding UTF-8". Solution: 1. In Netbeans: Right-click Project > Properties > Sources > Encoding: choose ISO i/o UTF-8 2. In Windows Explorer: Edit Program Files / Netbeans / netbeans.conf; find the line netbeans_default_options, insert -J-Dfile.encoding=UTF-8 at the end, inside quotes; restart NetBeans. 3. Eliminate accent characters in the comments and literals (<<, é, etc.). 2 Launching the application Problem: In Windows Explorer, when I click the link that refers to a.jnlp file, instead of launching Web Start, it opens the file in a text editor. Solution: In Windows Explorer, right-click the.jnlp file and select Open with > Choose default program ; then choose Java Web Start Launcher. Check Always use the selected program to open this kind of file. If you cannot fine Java Web Start Launcher, check if Java is installed on your machine. Figure 7: Association between Programs and File Extensions Problem: In my web browser, when I click the link that refers to a.jnlp file (stored on my machine), instead of launching Web Start, it opens the file in a text editor. Solution: In your web browser, associate the.jnlp file extension with the Web Start application. If you use Firefox (version 3.6.8), you can do that by Tools > Options > Applications > JNLP file Action set to Web Start Launcher. Chapter 5 - Troubleshooting 12

17 Problem: In my web browser, when I click the link that refers to a.jnlp file (stored on a remote server), instead of launching Web Start, it opens the file in a text editor. Solution: Your web server must associate.jnlp extension with the Java Web Start Launcher application. Consult the online document Common Java Web Start Problems2. Configure your web server to handle Java Network Launch Protocol (JNLP) files (see next question). Problem: How can I configure your web server to handle Java Network Launch Protocol (JNLP) files? Solution: The way to associate.jnlp file with Java Web Start Launcher may depend of the kind of web server you are using. In general, you should have a web.xml file in which insert a <mime-mapping> clause. Consult the online document Setting Up a Web Server3. Consult the Deploying Open ModelSphere on your own web server section of this document for further details. Problem: When I launch the application, I got the following error: JAR resources in JNLP file are not signed by the same certificate Solution: Ensure that in your org.modelsphere.jack project, the Enable Web Start checkbox is unchecked (in Project Properties > Application > WebStart), and is checked in your org.modelsphere.sms project. Ensure Project Properties > Application > Web Start > Self-signed checkbox is checked in the org.modelsphere.sms project, as illustrated below: Figure 8: Sms Project Properties Clean and build all your projects. Then delete any previous org.modelsphere.jack.jar and Chapter 5 - Troubleshooting 13

18 org.modelsphere.sms.jar on your web server, and replace them with freshly rebuilt archives. 3 Running the application Problem: Open ModelSphere seems starting, but fails during initialization. The error message is: java.lang.runtimeexception: Bad Installation: Cannot locate C:\Program Files (x86)\mozilla Firefox\targets directory at org.modelsphere.sms.plugins.targetsystem. <init>(targetsystem.java:205) Solution: Open ModelSphere tries to create a targets/ folder in your installation directory. It happens when you create a data model with new target system. This error should not happen in the context of a data viewer. Problem: Open ModelSphere seems starting, but fails during initialization. The error messages can be one of the following: Application Error: Unable to launch the application.". In Details: java.lang. ExceptionInInitializerError at org.modelsphere.sms.application.<clinit>(application.java:100). java.lang.reflect.invocationtargetexception: Caused by: java.lang.noclassdeffounderror: org.modelsphere.jack.international.localemgr Solution: The order in which classes are loaded are not necessarily the same for a standalone application or for a JWS application. Source code has to be changed to make it independent of the order in which classes may be loaded. If you encounter this message, it may involve changes to source code (see programming guidelines in the conclusion). Problem: Open ModelSphere starts, but if I open a large model, I get a Out of Memory error message. Solution: Increase your memory settings. In the.jnlp file, set the <j2se java-vm-args..> arguments to -Xss16m -Xms32m -Xmx1024m. You can also set these values directly in NetBeans (Right-click the project node, and select Properties > Run > VM Options). Problem: Open ModelSphere starts, but when I open an existing project, I get the following error: java.lang.runtimeexception: begintrans in AWT-EventQueue-0 while a transaction is active in AWT-EventQueue-0 at org.modelsphere.jack.basedb.db.db.begintransaux (Db.java:525) Solution: This error appears because an exception occurred during a transaction, and prevented the transaction to be correctly committed. When a second transaction tries to start, it fails because the first one is still running. The cause of this error is in the source code, and code has to be fixed to prevent this problem (it's not a configuration problem). An error like it appeared in build 912 (OMS 3.1) and was fixed in built 953 (OMS 3.2). The problem originates from the file AddElementPool.java, and the line: Chapter 5 - Troubleshooting 14

19 = GraphicUtil.loadIcon(DbBEUseCase.class, "./resources/dbbeumlmodel.gif"); was replaced with: = GraphicUtil.loadIcon(DbBEUseCase.class, "resources/dbbeumlmodel.gif"); If this error appears again, look for and remove the resource path starting with./ in the code. This error does not occur in standalone application, it occurs only in WebStart-deployed application. Chapter 5 - Troubleshooting 15

20 CHAPTER 6 - CONCLUSION WebStart-deployed Open ModelSphere revealed errors that were silent in the standalone Open ModelSphere. The following development guidelines may help to prevent WebStart-specific errors. 1 Prefer user.home over user.dir system property The user.home system property returns the same folder in the standalone and webstart mode. On Windows 7, it refers to C:\Users\Admin\, if Admin is the current user. On Windows XP, it refers to C:\Documents and Settings\Admin. The user.dir system property returns the folder when the application is installed. For a standalone Open ModelSphere running on Windows, it may be C:\Program Files\.. or C:\Program Files (x86)\.. if Open ModelSphere was installed with a program installer. If Open Modelsphere is launched from a batch (.bat) file on Windows, on from a shell script (.sh) on Linux, the user.dir will return the location where org.modelsphere.sms.jar is stored. user.home user.dir Standalone installed application on Windows 7 C:\Users\Admin\ C:\Program Files\.. or C:\Program Files (x86)\.. Standalone application on Windows 7, launched by a.bat file C:\Users\Admin\ The folder containing org.modelsphere.sms.jar Standalone application under development, using Netbeans or Eclipse on Windows 7 C:\Users\Admin\ The folder containing org.modelsphere.sms.application.class JWS application on Windows 7, launched from Firefox C:\Users\Admin\ C:\Program Files (x86)\mozilla Firefox JWS application under development, using Netbeans on Windows 7 C:\Users\Admin The folder containing launch.jnlp Standalone application on Windows XP C:\Documents and Settings\Admin\ C:\Program Files\.. JWS application on Windows XP, launched from Firefox C:\Program Files\Mozilla Firefox C:\Documents and Settings\Admin\ Table 2: Java system properties (assuming Admin is the current user) If Open ModelSphere is launched from Web Start, the user.dir system property may return the location of your web browser (for instance C:\Program Files (x86)\mozilla Firefox). It is preferable to avoid referring to user.dir, because the directory differs depending how the application is packaged (standalone or JWS), and also because user.dir may refer to a folder that the user does not have rights to write in. You should not write files in directories refered with the user.dir system property. Use the user.home folder instead. The user.dir must be limited to read-only contents. Chapter 6 - Conclusion 16

21 2 Remove accentuated characters in Java code Accented characters gives warnings when compiled with NetBeans. To reduce the number of Netbeans warnings, replace accentuated characters by ASCII characters. 3 Do not rely on the class loading order The order in which classes are loaded are not necessarily the same for a standalone application or for a JWS application. Source code has to be changed to make it independent of the order in which classes may be loaded The lazy initialization technique is preferable over the static loading technique. For instance, instead of writing: public class Application { public static final String PLUGIN_PATH = ApplicationContext.HOME_DIRECTORY; //presuming ApplicationContext is loaded before Application } It is preferable to write: public class Application { private static String PLUGIN_PATH; public static String getpluginpath() { if (PLUGIN_PATH == null) { PLUGIN_PATH = ApplicationContext.getHomeDirectory(); } } return PLUGIN_PATH; } //end getpluginpath() 4 String initialization These two statements are equivalent: String s = pluginpath ; String s = new String( pluginpath ); and behaves the same in standalone application. Is it true for JWS application? Chapter 6 - Conclusion 17

22 APPENDIX - ACRONYMS IDE Integrated Development Environment JAR Java Archive JNLP Java Network Launching Protocol JRE Java Runtime Environment JWS Java Web Start MB Mega Bytes MIME Multipurpose Internet Mail Extension OMS Open ModelSphere RC Release Candidate URL Uniform Resource Locator VM Virtual Machine Chapter 6 - Conclusion 18

23 REFERENCES These online references may be useful: Enable Java Web Start in the NetBeans IDE Overview Java WebStart Technology (Oracle) Debugging Java Web Start Applications Chapter 6 - Conclusion 19

24 INDEX MIME...11 A Apache...11 N C NetBeans...2 CPanel...11 P I Pluginpath...9 IIS...11 T J Tomcat...11 JNLP...8 U User.dir...16 Kenai...10 User.home...16 K M V VM Options...6 Chapter 6 - Conclusion 20