Application Server Installation¶
This chapter is out of date and is no longer being maintained. It is only being retained for historical purposes. The replacement chapter can be found in Application Server Installation.
This chapter documents how to install the runtime code that allows the FWD application server to execute. The configuration and execution of the server is documented in the Bootstrap Configuration, the various sections of Part 2 relating to the directory content and the Running the Server chapters. Installing the database server is separate from the application server, details can be found in Database Setup and Data Migration.
System Requirements¶
Hardware Requirements
The destination system should meet the following hardware requirements
| Feature | Requirement |
|---|---|
| CPU | Any recent Intelcompatible CPU will work. It is recommended to stay with a 32bit x86 processor since it greatly simplifies the installation of the runtime components. FWD has been tested to work on systems which can run 64bit code, however the installation requirements are more complicated for 64 bit. At this time the conversion process is singlethreaded. While a multicore CPU can be highly useful in running the conversion JVM, the benefit of those cores will not be as high due to this fact. The FWD runtime is highly threaded, so a multicore CPU environment will be of great benefit for this purpose. Both AMD and Intel CPUs have been tested and have been found to work well. If the JVM being used works well on a given CPU, then that CPU is OK. CPUs such as the Intel Core2 Duo have been found to be quite suitable for both conversion and runtime performance. |
| RAM | It is recommended to have at least 2GB of RAM and if possible 4GB of RAM. This will allow the comfortable hosting of the development environment, and both the conversion and runtime FWD processing. Small conversion projects can convert in less memory and the converted application may run in less, but for reasonable sized projects (1 million lines of code), the 2GB 4GB requirement should be considered a minimum. |
| Disk Space | The conversion process stores a great deal of state on the disk. Even medium sized projects may take 5GB of disk space to convert fully. Larger projects will require more space. It may also be useful to store more than one conversion project on the system. In addition, to the degree that a database data is being migrated, such migrations require space for the .d data export files as well as a significant amount of disk space for the imported database. Since Progress 4GL databases are very heavy in index usage and Progress is optimized to keep the index data small. Since the same logical indexes are maintained in the target runtime environment, the target database will have to maintain those indexes on disk. Common relational databases do not optimize the space of indexes to the same degree as Progress. This means it should be expected that the imported database will require significantly more disk space than the original Progress database. Consider the number of conversion projects, data export files and databases (including copies and test environments) and calculate disk space accordingly. |
Software Requirements
The destination system should meet the following software requirements
| Feature | Version | Requirement |
|---|---|---|
| Linux (or another UNIX compatible operating system) |
n/a | Java processes are normally platform neutral. When applications or tools are written in pure Java, it is possible for such processing to be run on any operating system or hardware platform that supports the proper level of the J2SE (Java 2 Standard Edition) required. At this time, while the vast majority of the client FWD code is written in pure Java, there is a small amount of platform specific code (written in C) used for character mode user interface processing and for process launching. That platformspecific code is implemented using the Java Native Interface (JNI) and is often referred to as “native” code. A customized version of that native code is included in the FWD project. This code is currently compiled as both 32bit and 64bit shared libraries for Linux. There may also be certain filesystem path dependencies, character/file encoding dependencies and/or other dependencies which would require a Linux or UNIX compatible system on which to run the conversion process. In particular, it is likely that the conversion process cannot be run unchanged on a Windows platform. FWD has been successfully run on a variety of recent Linux distributions from Ubuntu, SuSE, Red Hat and CentOS. There are no specific dependencies on any particular distribution. It is expected that any UNIXcompatible systemwould work properly. |
| Java Development Kit (JDK) | 6.0 or later | The Sun JDK 1.6 on Linux is a well tested option. Various versions from 1.6.0_04-b12 throuDoing so provides the PL/Java software running in the server's context with the information necessary to find and launch the Java Virtual Machine, in order to execute Java UDFs. These environment variables are most easily set by modifying the shell configuration gh 1.6.0_16-b01 have been tested and have been found to work well. Either the 32-bit or 64-bit version may be used. At the time of this writing, there has been no conversion project so large as to require more than 4GB of memory to successfully complete. For this reason, there is no strong requirement for the 64-bit JVM. For client usage, the 32-bit JVM is best. Since the memory requirements of server processes can be large, it is expected that the 64-bit version may be necessary for some installations. The application server process (JVM) is where the majority of working memory exists for each client (accessing the system). The actual memory used will depend on the queries, the block flow, recursion and other features of the original 4GL. The application code is actually running in the common server process, which is different from how Progress 4GL works (where the application runs in the client process unless an “appserver” is in use). However, for a development environment, it is less likely that 64-bit is needed. In general, try to use the 32-bit version unless there is a specific reason to do otherwise. The PATH for the user should be set to include the directory containing the command line executables (e.g. java or javac) of this installation. In Linux this would be the bin/ directory. In other words, this should be the default installation for any shell or command prompt from which the FWD technology will be built or used.GES: this next part is really about a build environment, not about the application server's runtime installation. Move it. It is also recommended to set the user's CLASSPATH (on Unix/Linux) as follows:export CLASSPATH=.It is also required for using correct makefile and gcc. |
| Apache Ant | 1.6 | GES: this next part is really about a build environment, not about the application server's runtime installation. Move it. Due to the ANTLR dependencies, version 1.5.3 does not work. Please ensure that Ant can be found via the user's PATH. |
| unzip | n/a | GES: this next part is really about a build environment, not about the application server's runtime installation. Move it. Among many options, the commonly available unzip utility can be used to extract files from a ZIP archive. This will need to be used to extract the FWD archive. |
Network requirements
Unless all the clients are on the same system as the application server there will be more network traffic with the FWD equivalent of the Progress 4GL because of the different approach of FWD.
Generally, there is one socket opened for each user and that socket is kept open for the duration of the user's session. If there are application and/or batch programs that connect to the FWD server, then there is at least one socket open for each of them. Hand coded applications can create more than 1 session with the server, if they do that, there is 1 socket per session.
At this time, there is not yet developed a set of specific equations that can be used to estimate the network traffic, since there are many variable factors.
In conclusion, it does make sense to ensure good performance for the network connection between the clients and the application server in order to achieve optimal performance.
Choosing the Appropriate JVM¶
From performance point of view in most cases the 32bit JVM is the recommended choice since it slightly outperforms the 64 bit one up to a certain value of cache size. However the 64 bit JVM becomes better for large cache sizes (larger than 25 GB) because the 32 bit one has a much smaller heap size. Generally the 64 bit JVM will consume more memory than the 32 bit one , using a 32bit JVM instead of a 64bit JVM greatly reduces the memory footprint of each client JVM which can be huge on a server that is dedicated to running CHUI clients; it also has implications for building the JNI libraries libTerminal.so and libp2j.so .
Also when choosing a 64 bit JVM you'll have to build the PL/Java from source. Building PL/Java from source can be a bit tricky and is a topic beyond. the scope of this chapter. Please refer to the PL/Java project documentation and the Advanced Setup chapter if you have this need.
Installation Process¶
Install FWD Project Code
The FWD project code should be available as a ZIP format archive file. This archive should include all of the source code and supporting files needed to build the FWD project on a given system.
For the sake of this example, assume that the zip file name is ~/p2j_20100620.zip and that the p2j code is to be installed in a directory named ~/projects. Given these assumptions, installation is as simple as the following commands to extract the zip file:
cd ~/projects unzip ~/p2j_20100620.zip
A directory ~/projects/p2j will be created with the entire contents of the FWD project. For the remainder of the chapter, the environment variable $P2J will be a reference to ~/projects/p2j.
This can be "saved" into the environment to simplify subsequent commands:
export P2J=~/projects/p2j
Build FWD
GES: This build stuff needs to have its own chapter. It also needs to have all the build environment dependencies documented, including the native target stuff (which builds libp2j.so and needs libncurses-dev and make, gcc...). Some of the content in the software dependencies chapter needs to be reworked and moved there.
The FWD project must be built. This will compile all code and then create jar files that store the compiled code. The commands:
cd $P2J ant all
All of the FWD conversion and runtime tools are stored in a single file called p2j.jar. That file in turn is dependent upon other jar files, which have been specified in the p2j.jar file's manifest. This means that as long as the p2j.jar can be found in the Java CLASSPATH and those other jar files exist in the same directory, the tools will work properly.
The p2j.jar can be found in the $P2J/build/lib/ directory, along with each of the dependent jar files which are shipped with the FWD project. It is best to use those versions since they are tested and are known to work.
When running FWD commands, it will be necessary to use the -classpath $P2J/build/lib/p2j.jar:. parameter on the java command line.
Necessary jar files
Copy the following list of jar files from the FWD production build to be used (it is possible that the jars highlighted in red can be left out, however at this time testing has not proven this definitively):
- p2j/build/lib/antlr.jar
- p2j/build/lib/asm.jar
- p2j/build/lib/c3p0-0.9.1.jar
- p2j/build/lib/cglib-2.1_3.jar
- p2j/build/lib/charva.jar
- p2j/build/lib/commons-beanutils-core.jar
- p2j/build/lib/commons-codec-1.3.jar
- p2j/build/lib/commons-collections-2.1.1.jar
- p2j/build/lib/commons-digester.jar
- p2j/build/lib/commons-logging-1.0.4.jar
- p2j/build/lib/dom4j-1.6.jar
- p2j/build/lib/ehcache-1.1.jar
- p2j/build/lib/h2.jar
- p2j/build/lib/hibernate3.jar
- p2j/build/lib/jetty-6.1.14.jar
- p2j/build/lib/jetty-util-6.1.14.jar
- p2j/build/lib/jta.jar
- p2j/build/lib/p2jadmin.jar
- p2j/build/lib/p2j.jar
- p2j/build/lib/p2jpl.jar
- p2j/build/lib/p2jrt.jar
- p2j/build/lib/p2jspi.jar
- p2j/build/lib/postgresql-8.2-508.jdbc4.jar
- p2j/build/lib/servlet-api-2.5-6.1.14.jar
These files must all be copied to the same target directory on the application server system.
Text colator
Copy the text collator (used to customize H2 database sorting) into the installed JDK's extension directory. This collator is the jar file p2j/build/lib/p2jspi.jar (found in the FWD production build) which must be copied into the $JAVA_HOME/jre/lib/ext/ directory of the installed JDK which will be used to run the application server.
Converted application
Copy the converted application jar files from the production build directory into a directory on the application server system. That directory can be the same as where the FWD jars reside or it can be a different directory. Usually, these will be found in the conversion project home directory as built/lib/*.jar. These will NOT be found under p2j/build/lib/.
Arbitrary customer-specific Java application code can be loaded, run and accessed inside the FWD Application Server. Copy any customer-specific application jar files into a directory on the application server system. It can be the same or a different directory as the location of the FWD and converted application jar files.
Server configuration files
Copy the following server configuration files into a directory on the application server system which will be the current or working directory for the FWD application server process:
- fully configured directory file(s)
- server bootstrap configuration file(s)
- server key store(s)
- server trust store
Server user account
Create an user account on the application server system under which context the FWD application server will run. It is OK to run as root however this is generally not needed, nor it is advisable.
Ensure that the FWD application server's user account has the following permissions:
- it must be able to launch a java process with the necessary amount of RAM to provide for the maximum heap size + some amount of overhead in the JVM itself
- it must be able to read all of the jar files copied from the FWD build
- it must be able to read all of the jar files copied from the converted application build
- it must be able to read all of the customer-specific application jar files
- it must have read and write and change directory access to the entire contents of the directory in which the FWD application server configuration files have been copied (note that the FWD application server may edit the configuration files and will write its log files to this directory)
- it must be able to establish an outbound TCP socket connection (with subsequent 2-way communication) to the Database Server host and port needed for the database access
- it must be able to open and listen for inbound TCP socket connections (with subsequent 2-way communication) on at least 1-3 ports (a secure socket, an insecure socket and an administrative HTTPS server socket)
Firewall
Any firewall support must be configured to allow the following:
- outbound TCP socket connection (with subsequent 2-way communication) to the Database Server host and port needed for the database access
- inbound TCP socket connections (with subsequent 2-way communication) on at least 1-3 ports (a secure socket, an insecure socket and an administrative HTTPS server socket)
File System Structure¶
Here is a list of server component files and their role and description (it is possible that the jars highlighted in red can be left out, however at this time testing has not proven this definitively)
| File name | Description |
|---|---|
| p2j/build/lib/antlr.jar | ANTLR is a tool for Language Recognition, is a language tool that provides a framework for constructing recognizers, interpreters, compilers, and translators from grammatical descriptions containing actions in a variety of target languages. ANTLR provides excellent support for tree construction, tree walking, translation, error recovery, and error reporting. |
| p2j/build/lib/asm.jar | ASM is an all purpose Java bytecode manipulation and analysis framework. It can be used to modify existing classes or dynamically generate classes, directly in binary form. Provided common transformations and analysis algorithms allow to easily assemble custom complex transformations and code analysis tools. |
| p2j/build/lib/c3p0-0.9.1.jar | c3p0 is an easy-to-use library for augmenting traditional (DriverManager-based) JDBC drivers with JNDI-bindable DataSources, including DataSources that implement Connection and Statement Pooling, as described by the jdbc3 spec and jdbc2 std extension. |
| p2j/build/lib/cglib-2.1_3.jar | cglib is a Code Generation Library, It is used to extend JAVA classes and implements interfaces at runtime |
| p2j/build/lib/charva.jar | CHARVA is a Java framework for presenting a "graphical" user interface, composed of elements such as windows, dialogs, menus, textfields and buttons, on a traditional character-cell ASCII terminal. |
| p2j/build/lib/commons-beanutils-core.jar | Commons BeanUtils core provides dynamic access to Java object properties (without compiled-in knowledge of the property getter and setter methods to be called) is needed.(this does not include the Bean Collection classes). |
| p2j/build/lib/commons-codec-1.3.jar | Apache Commons Codec provides implementations of common encoders and decoders such as Base64, Hex, Phonetic and URLs. |
| p2j/build/lib/commons-collections-2.1.1.jar | Commons-Collections seek to build upon the JDK classes by providing new interfaces, implementations and utilities. |
| p2j/build/lib/commons-logging-1.0.4.jar | The Commons Logging package is an ultra-thin bridge between different logging implementations. A library that uses the commons-logging API can be used with any logging implementation at runtime. Commons-logging comes with support for a number of popular logging implementations, and writing adapters for others is a reasonably simple task. |
| p2j/build/lib/dom4j-1.6.jar | dom4j is an easy to use, open source library for working with XML, XPath and XSLT on the Java platform using the Java Collections Framework and with full support for DOM, SAX and JAXP |
| p2j/build/lib/hibernate3.jar | Hibernate is a high-performance Object/Relational persistence and query service, Hibernate takes care of the mapping from Java classes to database tables and from Java data types to SQL data types. It provides data query and retrieval facilities that significantly reduce development time. Hibernate3.jar contains a list of artifacts of multiple hibernate projects for the purpose of providing all the needed hibernate functionality inside a single jar. |
| p2j/build/lib/h2.jar | h2.jar drivers for H2 Database |
| p2j/build/lib/ehcache-1.1.jar | Ehcache is an open source, standards-based cache used to boost performance, offload the database and simplify scalability. It can scale from in-process with one or more nodes through to a mixed in-process/out-of-process configuration with terabyte-sized caches. |
| p2j/build/lib/jetty-6.1.14.jar | Jetty provides an HTTP server, HTTP client, and javax.servlet container. jetty-6.1.14.jar core project |
| p2j/build/lib/jetty-util-6.1.14.jar | Jetty-util-6.1.14.jar Jetty utility classes. |
| p2j/build/lib/jta.jar | Java Transaction API (JTA) specifies standard Java interfaces between a transaction manager and the parties involved in a distributed transaction system: the resource manager, the application server, and the transactional applications. |
| p2j/build/lib/p2jadmin.jar | p2jadmin.jar contains the minimum FWD runtime code needed to run the Administration Console, which is implemented as an applet. This jar is dynamically sent down to the browser and it contains all code needed to make the connection to the FWD server and to call all the admin APIs. Of course, it also has the swing based GUI code that implements the UI. All of the real work happens on the server, behind the admin API. The applet is just the user interface to it. This jar is not used by the server (because all the server-side classes are already part of the p2j.jar). But it still needs to be included in the classpath so that the server can find the jar when it needs to send it down to the browser. |
| p2j/build/lib/p2j.jar | p2j.jar inside this file are stored all the FWD conversion and most of the runtime tools. |
| p2j/build/lib/p2jpl.jar | p2jpl.jar contains the minimum FWD runtime code that is needed to run user-defined functions (written in Java) inside PostgreSQL. It includes the functions themselves as well as the supporting data types and so forth. This is "registered" with PLJava. There should be details on this in the dev guide. |
| p2j/build/lib/p2jspi.jar | p2jspi.jar is the collation service provider that we use to get H2 to sort in the same way that Progress does. There are details in the dev guide. It has to be installed as an extension of the JRE, so it must be copied into the $JAVA_HOME/jre/lib/ext/ directory of the installed JDK |
| p2j/build/lib/postgresql-8.2-508.jdbc4.jar | PostgreSQL jdbc drivers |
| P2j/build/lib/servlet-api-2.5-6.1.14.jar | The Java Servlet API includes several Java interfaces and fully defines the link between a hosting server and servlets. The Servlet API is defined as an extension to the standard JDK. |
| built/lib/*.jar. | The converted application jar |
| directory.xml | directory.xml Required if using the XML backend. Defines the xml file that provides persistent storage for the directory. |
| server.xml | server.xml Bootstrap configuration file which hold the minimum configuration values needed to name the server/client, initialize the network and and either connect to the server (if this node is a client) or to connect to the directory server (if this node is a server). All other configuration data is stored in the FWD Directory. |
| key.store | The keystore is a password protected storage file for a private key, which is encrypted and decrypted using the given password. This allows a slightly better level of security than without the encryption. However it is essential that both the keystore and the password be kept in a secure location |
| trust.store | A truststore file is needed for FWD clients to validate an SSL connection with a FWD server . It contains the certificates for the root CA and for the FWD servers to be validated. It is possible to connect to the FWD server via SSL without using SSL handshake validation. The truststore is only needed if validation is used. |
© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.