MapXtreme Java Edition Install Guide

Transcription

1 MapXtreme Java Edition Install Guide Americas: Phone: Fax: Sales: Government Sales: Technical Support: UK and EMEA: Phone: Fax: Technical Support: Asia Pacific: Phone: Fax: Technical Support: Pitney Bowes Software Inc. All rights reserved. MapInfo, the Pitney Bowes MapInfo logo, and Product Name only (no version number) are trademarks of Pitney Bowes Software Inc. and/or its affiliates. November 10, 2008 This guide describes the steps you must follow to perform a MapXtreme Java installation. MapXtreme Java is a set of 100% Pure Java classes (Java 2 compliant), which allow you to deploy your application on the system you have, whether it is Windows, UNIX, or both. Table of Contents Release Notes and Documentation Installing MapXtreme Java Post Installation Tasks Uninstalling MapXtreme Java Apache-Tomcat Deployment Environment Deploying MapXtreme Java in Other Web Environments Configuration Troubleshooting Release Notes and Documentation Before installing MapXtreme Java, you must read the MapXtreme Java Release Notes. These notes are the most recent source of information you need to know to install and use MapXtreme Java. Included in these notes are the system requirements and all known issues for the current release. The Release Notes are in the MapXtreme Java Documentation Library at reference.mapinfo.com/ mapxtremejava. The MapXtreme Java Documentation Library contains the latest versions of all MapXtreme Java guides in PDF and HTML formats. You can view the documents individually or download the entire library to your computer as a ZIP file. The guides in the library are updated as needed. Installing MapXtreme Java MapXtreme Java can be installed on any system that supports a Java 2 Virtual Machine. The installation program installs the MapXtreme Java server, client, samples, documentation, and an example deployment environment. You can install MapXtreme Java using either a graphical or command-line installer. The graphical installer guides you through the installation process by asking a series of questions (process described in this section). This is the installer that is recommended for most users to install MapXtreme Java.

2 The command-line installer allows you to install MapXtreme Java from the command prompt using scripts. The command-line installer requires you to specify your installation preferences before running the installer. Pitney Bowes MapInfo expects only advanced users whose environments require a command-line installer to use this method. See Installing in Silent Mode on page 6 for instructions how to install using the command-line installer. To install MapXtreme Java using the installer: 1. Choose the appropriate MapXtreme Java CD for your installation platform, and place it in your CD-ROM drive: a. CD1 contains files for Windows, Solaris, and Linux. b. CD2 contains files for IBM AIX, HP-UX, and other UNIX. 2. Run install.htm from the CD root and select the link for your platform. Select the link for your platform: Windows, Solaris, Linux, or HP-UX. Alternatively, for the appropriate platform: Windows At the CD1 root, go to \InstData\Windows\VM and run install.exe. Solaris At the CD1 root, go to /InstData/Solaris/VM and run install.bin. Linux At the CD1 root, go to /InstData/Linux/VM and run install.bin. IBM AIX At the CD2 root, go to /InstData/AIX/VM and run install.bin. HP-UX At the CD2 root, go to /InstData/HPUX/VM and run install.bin. UNIX At the CD2 root, go to /InstData/GenericUnix and run install.bin. 3. When the MapXtreme Java installation starts, choose a language and click OK. 4. At the Introduction, review the information and click Next to proceed. MapXtreme Java Install Guide 2

3 5. Review the agreement. If you agree with the agreement, then select I accept... and click Next to continue with the installation. Otherwise, select I do NOT accept... and click Cancel to exit the installer. 6. Either accept the default location to install the MapXtreme Java or click Choose... and browse to another location. The Windows default location is <SYSTEM_DRIVE>\Program Files\MapInfo\MapXtreme-X.x.x, where X.x.x is the current version of MapXtreme Java. On Solaris, Linux, and HP-UX, the default location is /user/home/mapinfo/ MapXtreme-X.x.x. Click Next. Note If you attempt to install to a location where an existing version of MapXtreme Java exists, you will receive the following warning: MapXtreme Java Install Guide 3

4 7. Depending on your operating system, you will see options to either choose shortcuts (Windows) or choose the links directory. If you are using Windows, select where you want to create MapXtreme Java shortcuts and click Next. If you are using UNIX or Linux, select where you want to create MapXtreme Java links and click Next. 8. Either choose to install the JVM bundled with the installer or select one that is already installed (this must be a JVM or higher). Click Next. The installer will configure MapXtreme Java to use this virtual machine. If you choose to have the MapXtreme Java install the JVM, the following version will be installed depending on your operating system: Windows: Sun JRE 1.5.0_11 I18N Win32 AIX: IBM JRE AIX build pap32dev HP-UX: Hewlett-Packard JRE HP-UX Linux: Sun JRE 1.5.0_11 Linux INTEL Solaris: Sun JRE 1.5.0_09 Solaris SPARC MapXtreme Java Install Guide 4

5 9. Specify the hostname and port number for the Tomcat instance that will be deployed. This Tomcat instance will host the MapXtreme Java servlet and samples. Click Next. 10. Review the pre-installation information and click Install, or click Previous to make changes. The MapXtreme Java install launches. MapXtreme Java Install Guide 5

6 11. When the install is completed, click Done to exit the installer. This completes the MapXtreme Java installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use MapXtreme Java. For the remaining tasks, see Post Installation Tasks on page 7. Installing in Silent Mode MapXtreme Java provides a command-line installer using the silentinstall.properties file to use when installing MapXtreme without a GUI. This file is located in the root folder on the CD-ROM. You must customize the variables in the silentinstall.properties file to suit your particular needs. The format of this file follows a simple <variable>=<value> form. These variables must be populated with valid values in order for the install to execute properly. To run a command-line silent install: 1. Copy the silentinstall.properties file from the CD to a folder on your local machine where you can edit it, and open the file in a text editor. 2. In the silentinstall.properties file, change the following variables as needed: USER_INSTALL_DIR the install location of the application files WEB_ENV_1 the host server name WEB_ENV_2 the port JAVA_HOME the JAVA_HOME directory if you do not wish to install the bundled JVM USER_SHORTCUTS the location to install the symbolic links Note All variables are required except JAVA_HOME and USER_SHORTCUTS. 3. Run the installer, passing in the modified silentinstall.properties file. For example, run the following command to execute a silent install in Linux: /cdrom/instdata/linux/vm/install.bin -f COPIED_FILE_PATH/silentinstall.properties Note The COPIED_FILE_PATH must be the full path to the file. This completes the MapXtreme Java installation process, however, there are additional tasks you must perform to configure the installation. You must perform these tasks to successfully use MapXtreme Java. For the remaining tasks, see Post Installation Tasks on page 7. MapXtreme Java Install Guide 6

7 Installed Components The following outlines the key components included in MapXtreme Java. A short description of each follows. MapXtreme Java Manager This is a GUI tool that allows you to manage several aspects of MapXtreme Java, including create and load map definitions, manage named resources, manage JDBC connections to RDBMSs, and build prototypes and applications with the help of a wizard. MapJ API and Java Class Library The MapJ API, class library, and JavaDocs provide everything you need to build customized applications, applets, servlets, and JavaBeans. JSP Tag Library MapXtreme Java includes a set of custom JSP tags to assist you with rapid prototype and application building. Custom Symbols MapXtreme Java installs a folder of custom symbol GIF images. These images are located in the MapXtreme- X.x.x\support\symbols\Custom directory, where X.x.x is the current version of MapXtreme Java. MapXtreme Java also provides pre-defined renditions for pen, brush, and symbol fonts. Use these to customize your map layers. These files are located in the MapXtreme Java servlet under \resources\mistyles. Samples MapXtreme Java includes a variety of sample servlets and applets that demonstrate key elements of MapXtreme Java. Most can be found in the /examples directory after installation. Several of these sample applications include an HTML tutorial that explains the features and the code. In addition, pre-compiled versions can be found in the MapXtreme- X.x.x/lib/client/mxjclientsamples.jar and MapXtreme-X.x.x/lib/server/mxjserversamples.jar, where X.x.x is the current version of MapXtreme Java. Post Installation Tasks Adding JDBC Drivers to Your Classpath To access data from remote databases using JDBC, you must manually add the appropriate drivers to your classpath in the MapXtreme Java Manager.lax file (see LAX Files on page 12 for more information). For example, if you are using the MapXtreme Java Manager Standalone version and want to access data in an Oracle database, go into \MapXtreme-X.x.x\bin\MapXtremeJavaManager-StandAlone.lax and add the path to classes12.zip to the list in the classpath. When using MapXtreme Java Manager Web Server, add the information to \MapXtreme- X.x.x\bin\MapXtremeJavaManager-WebServer.lax, where X.x.x is the current version of MapXtreme Java. Adding Fonts to Your Classpath To access the fonts from your applications, you must manually add the mifonts.jar file to your classpath. This file is located in the \MapXtreme-X.x.x\\lib\common\ directory, where X.x.x is the current version of MapXtreme Java. ECW Raster Integration for Solaris When starting your application server or standalone MapXtreme Java Manager, if you encounter the following message in your command prompt, the ECW raster support is not configured properly for your Solaris installation. NOTE:* * * * * * * * * * * * * * * * * * * * * * * MapXtreme Java Install Guide 7

8 GCC library files were not found in /usr/local/lib ECW raster images will not display correctly. Set LD_LIBRARY_PATH to include the directory containing libstdc++.so.6 and libgcc_s.so.1 NOTE:* * * * * * * * * * * * * * * * * * * * * * * To display ECW raster images on a Solaris machine, you must have a GNU C Compiler (GCC) v3.4.6 or later installed and set your LD_LIBRARY_PATH environment variable to include the GCC binaries. You can obtain the GCC binaries from Your complete startup script should look similar to the following: CATALINA_HOME="/home/mapinfo/MapXtreme-4.8.2/apache-tomcat-5.5" CATALINA_BASE="/home/mapinfo/MapXtreme-4.8.2/apache-tomcat-5.5" JAVA_OPTS="-Xms128m -Xmx512m -Djava.library.path=/home/mapinfo/MapXtreme-4.8.2/lib/ native/solaris" LD_LIBRARY_PATH="/user/GCC/lib:$LD_LIBRARY_PATH" JRE_HOME="/home/mapinfo/jre1.5.0_11" export JRE_HOME CATALINA_HOME CATALINA_BASE JAVA_OPTS LD_LIBRARY_PATH cd "/home/mapinfo/mapxtreme-4.8.2/bin" sh "$CATALINA_HOME/bin/catalina.sh" run -config "$CATALINA_BASE/conf/server.xml" & Software Copy Protection If your copy of MapXtreme Java is copy protected (i.e., a watermark "Protected Software - Key Required for Permanent Use" is visible on maps displayed in MapXtreme Java Manager), you will need to apply for a license file that will remove the watermark and make MapXtreme Java available for permanent use. To remove the watermark from the map display: 1. Do one of the following: Fill out the copy protection key application entitled "Important Please Read" provided in the MapXtreme Java product package. or Download the application form from the MapXtreme Java Documentation Library at reference.mapinfo.com/ mapxtremejava. Click on the link and choose Software Copy Protection License Application. 2. Submit the completed form to your distributor or reseller. See form for contact information. Your distributor will process your application and send you a license file by . After receiving the license file called mapxtremejava.key, place it in a directory that is on your classpath, for example, C:/Program Files/MapInfo/MapXtreme-X.x.x/lib/client, where X.x.x is the current version of MapXtreme Java. This file also needs to be on the server s classpath, so for the MapXtreme Java servlet, place this file in the servers WEB-INF/ classes directory. Create the /classes directory if you do not have one. Your maps will now display without the watermark Uninstalling MapXtreme Java To uninstall MapXtreme Java from Windows, choose the uninstall shortcut on the Program menu under MapXtreme Java or run the uninstall.exe from the directory <INSTALL_DIR>\UninstallMapXtremeJavaX.x.x, where X.x.x is the current version of MapXtreme Java. To uninstall MapXtreme Java from Solaris, Linux, or HP-UX, run the uninstall.sh from the directory <INSTALL_DIR>/ UninstallMapXtremeJava-X.x.x. MapXtreme Java Install Guide 8

9 Apache-Tomcat Deployment Environment MapXtreme Java uses a servlet model to service requests. MapXtreme Java requires a web server/servlet container to run, such as Apache-Tomcat, WebLogic, Oracle and others. As a convenience to users, we install and integrate Apache-Tomcat with MapXtreme Java as part of the product installation. After installation, you will find the Apache-Tomcat directory under <INSTALL_DIR>\MapXtreme-X.x.x\apache-tomcat- Y.y, where X.x.x is the current version of MapXtreme Java and Y.y is the current version of Tomcat. In the <INSTALL_ DIR>\MapXtreme-X.x.x\apache-tomcat-x.x\webapps directory will be a the servlet contexts for MapXtreme Java, Mapviewer JSP sample, other sample applications, and a OGC compliant WMS Server. Multiple Instances of Apache-Tomcat Using multiple instances of Apache-Tomcat can increase MapXtreme Java s performance. On some Solaris servers with four or more CPUs, MapXtreme Java s performance improves when there are three instances of Tomcat running concurrently. For example, your server might run Apache and three Tomcat instances, and the Tomcat setup (e.g., mod-jk.conf) can perform load balancing among the Tomcat instances. If you have multiple Tomcat instances on the same computer, you will need to modify your Tomcat configuration so that each instance listens on a different port number. For example, you will want to have multiple copies of the server.xml file (e.g., server2.xml, server3.xml), each of which designates a unique port number and a unique workdir setting, so that the multiple Tomcat instances do not conflict. You will also need to start each Tomcat instance with the optional -f argument to designate which xml file you wish to use. For example: tomcat start -f../conf/server2.xml Note Load balancing is not necessarily limited to one computer. For example, you might have Tomcat running on several computers, with Apache performing load balancing. Deploying MapXtreme Java in Other Web Environments As part of the installation process, web archive (war) files are created and placed in the <INSTALL_DIR>\MapXtreme- X.x.x\wars directory, where X.x.x is the current version of MapXtreme Java. The war files are: mapxtremexxx.war the main mapxtreme context mapviewerxxx.war the JSP sample MapViewer web application samplesxxx.war servlet sample applications wmsserver111.war context for Web Map Service (WMS) These war files can be deployed in any servlet container that supports WAR files. Note These files have information in them that ties them to the host machine on which they were installed. ECW Raster Integration If you are adding MapXtreme Java to your own application server, and your application requires the ability to display ECW raster images, you must set the Java system property java.library.path to the directory containing the native libraries for these image types. When the installer installs MapXtreme Java, it creates the folder <InstallDir>/ MapXtreme-X.x.x/lib/native. Depending on your operating system, set java.library.path to the folder containing the correct version of the libraries (Win32 or linux). On a server running Tomcat, set the environment variable JAVA_OPTS or CATALINA_OPTS with a "-D" argument before calling startup.bat. For example, on a 64-bit Linux server running Tomcat: JAVA_OPTS=-Djava.library.path="<home>/MapInfo/MapXtreme-4.8.2/lib/native/linux" MapXtreme Java Install Guide 9

10 Solaris Instance Integration In addition to setting the java.library.path, you must set your LD_LIBRARY_PATH to point to your GNU C Compiler binary files. To display ECW raster images on a Solaris machine, you must have a GNU C Compiler (GCC) v3.4.6 or later installed and set your LD_LIBRARY_PATH environment variable to include the GCC binaries. You can obtain the GCC binaries from Your complete startup script should look similar to the following: CATALINA_HOME="/home/mapinfo/MapXtreme-4.8.2/apache-tomcat-5.5" CATALINA_BASE="/home/mapinfo/MapXtreme-4.8.2/apache-tomcat-5.5" JAVA_OPTS="-Xms128m -Xmx512m -Djava.library.path=/home/mapinfo/MapXtreme-4.8.2/lib/ native/solaris" LD_LIBRARY_PATH="/user/GCC/lib:$LD_LIBRARY_PATH" JRE_HOME="/home/mapinfo/jre1.5.0_11" export JRE_HOME CATALINA_HOME CATALINA_BASE JAVA_OPTS LD_LIBRARY_PATH cd "/home/mapinfo/mapxtreme-4.8.2/bin" sh "$CATALINA_HOME/bin/catalina.sh" run -config "$CATALINA_BASE/conf/server.xml" & When starting your application server or standalone MapXtreme Java Manager, if you encounter the following message in your command prompt, the ECW raster support is not configured properly for your Solaris installation. NOTE:* * * * * * * * * * * * * * * * * * * * * * * GCC library files were not found in /usr/local/lib ECW raster images will not display correctly. Set LD_LIBRARY_PATH to include the directory containing libstdc++.so.6 and libgcc_s.so.1 NOTE:* * * * * * * * * * * * * * * * * * * * * * * Configuration Troubleshooting If you encounter a configuration problem that prevents the MapXtreme Java servlet from servicing mapping requests, once you have installed MapXtreme Java and set it up in a servlet container, use the following information. For example, if you try to deploy the sample applet, SimpleMap, the applet might report a FileNotFoundException referring to the URL of your MapXtreme Java servlet. If you experience such an error, there are two main possibilities: The MapXtreme Java servlet might not be configured correctly. You might not be specifying the correct URL to access the MapXtreme Java servlet. To troubleshoot this type of problem, make sure your server is started and run a "debug" URL. A status page will display indicating that the MapXtreme Java servlet is running and the URL is correct. In your browser s URL text field, type the URL to your MapXtreme Java servlet, followed by "?debug=true". For example: where Xxx is the current version of MapXtreme Java The status page will show basic diagnostic information, including the version of the Java VM and the version of MapXtreme Java in use. If you do not see this status page, either the servlet is not running or the URL is not correct. Verifying the MapXtreme Java Servlet Is Running You can check if the MapXtreme Java servlet is running by watching the startup process. As your servlet container launches, watch for any indication of errors. For example, if your servlet container has a console window or log that you can view, view the console or log for any messages that refer to "MapXtremeServlet" or "mapxtreme". MapXtreme Java Install Guide 10

11 If your servlet container provides an administrator tool, you should be able to check the status of the MapXtreme Java servlet by running your administrator. If your servlet container does not provide an administrator tool, try viewing a console window or log to see whether the MapXtreme Java servlet started. The exact text that appears in your console window or log will depend in part on which servlet container you use. In general, if the MapXtreme Java servlet is initialized successfully, you should see an "init" message. For example, if Tomcat is configured correctly, the Tomcat console or log file shows the following text: Context log path="/mapxtremexxx" :mapxtreme: init where Xxx is the current version of MapXtreme Java These messages indicate that the web.xml file for MapXtreme Java was processed, and the MapXtreme Java servlet was initialized correctly. Note that the status message above says "mapxtreme: init" instead of "com.mapinfo.mapxtreme.mapxtremeservlet: init". This is because MapXtreme Java's installer assigns the MapXtreme Java servlet a registered name of "mapxtreme"; see the MapXtreme Java web.xml file located in your mapxtremexxx/web-inf servlet directory, where Xxx is the current version of MapXtreme Java If the MapXtreme Java servlet does not initialize when you start your servlet container, it does not necessarily mean that there is a problem. It might simply mean that the MapXtreme Java servlet configuration did not set the Load On Startup option to True (and hence, the MapXtreme Java servlet has not yet been initialized because there have not yet been any requests for it). Installing Tomcat using the MapXtreme Java installer does set Load On Startup to True, so Tomcat users should see an "init" message, as shown above, when Tomcat is started. If you are having difficulty verifying that MapXtreme Java servlet is configured correctly, you should configure MapXtreme Java so that it is set to Load On Startup, and then restart your servlet container. In Tomcat, the Load On Startup option is specified in the web.xml, located in your mapxtremexxx/web-inf servlet directory, using the <loadon-startup> tag. If your servlet container provides an administrator tool, you can probably set the Load On Startup option in the administrator. If your MapXtreme Java servlet deployment descriptor is set to Load On Startup, and you still do not see an "init" message in the servlet container's console or log, then there is probably an error in how MapXtreme Java is configured; in this case, review the steps that you used to configure MapXtreme Java, to make sure all configuration steps were performed correctly. Verifying the URL for the MapXtreme Java Servlet Before you can take advantage of your MapXtreme Java servlet, you need to know its precise URL. For example, before you can run the sample applet, SimpleMap, you need to edit the HTML file that loads the applet, and specify the URL to your MapXtreme Java servlet. Note URLs are case-sensitive. The general form of a MapXtreme Java servlet URL is as follows: hostname: This depends on the name or IP address of your server. If you are running everything on one computer (e.g., for testing or development), you might use "localhost" for your hostname. portnumber: This depends on how you set up your servlet container. If you ran MapXtreme Java's installer and accepted the defaults, this should be port If you have configured your servlet container to use port 8080, you can omit the port number (and the colon) when you specify the MapXtreme Java servlet URL. path: This depends on your servlet container, and may also depend on what sub-directories you created. See examples below. registeredname: This is a name that you can specify, such as "mapxtreme", which acts as a shortcut to the com.mapinfo.mapxtreme.mapxtremeservlet class. It is not a strict requirement that you use a shortcut; you can specify com.mapinfo.mapxtreme.mapxtremeservlet as the final part of your URL. However, if you have set up a registered name for the MapXtreme Java servlet, then you should use that registered name. (Any configuration options MapXtreme Java Install Guide 11

12 that you specified in your deployment descriptor, such as Load On Startup options, are associated with the registered name; if you use an URL that specifies the class name rather than the registered name, then those options will not take effect.) If you are using the example deployment environment (Tomcat) that comes with MapXtreme Java and you accepted the defaults, then your MapXtreme Java servlet URL should be: where Xxx is the current version of MapXtreme Java. In this example, the /mapxtremexxx segment of the URL signifies the MapXtreme Java directory created inside the Tomcat directory. The ending segment, /mapxtreme, refers to the registered name that the installer places into <tomcat_home>/mapxtremexxx/web-inf/web.xml, using the <servlet-name> tag. To verify this, run a "debug" URL. A status page will display indicating that the MapXtreme Java servlet is running and the URL is correct. In your browser s URL text field, type the URL to your MapXtreme Java servlet, followed by "?debug=true". For example: LAX Files The MapXtreme Java installer places several configuration files on your system that relate to the executables for MapXtreme Java Manager and Uninstaller. These files, with the extension.lax (e.g., MapXtreme Java Manager.lax) provide important configuration information about your system: lax.class.path Add any JDBC drivers you need to the list of jar files here. For example, to access Oracle with Spatial Option, add classes12.zip to the classpath. lax.stderr.redirect For debugging, put =console at the end to send the information to a console window. lax.stdout.redirect Put =console at the end for debugging, as above. lax.nl.current.vm Check the version of the VM, if it s not working. MapXtreme Java Install Guide 12