Natural for Ajax consists of a J2EE enterprise application (njx12.ear) and a J2EE resource adapter (njx12ra.rar). Both components are to be deployed on a J2EE server. Natural for Ajax receives data from Natural applications running on a Windows, UNIX or mainframe host and delivers web pages to the user's web browser.
This document describes the installation of Natural for Ajax on application servers on Windows or UNIX. It does not describe the installation of the additionally required Natural components on a Windows, UNIX or mainframe host, but refers to the corresponding installation documents.
This document covers the following topics:
For information on how to activate the preconfigured security settings of Natural for Ajax and how to adapt them to your requirements, see Configuring Security in the Configuring the Client part of the Natural Web I/O Interface documentation.
The following topics are covered below:
JDK 1.5.0_12 or above is required.
The following application servers are supported. The application servers are not delivered with Natural for Ajax. They can be obtained from the locations indicated below, according to their respective license terms.
JBoss Application Server 4.0.5 and 4.2.2 (see http://www.jboss.org/).
Sun Java System Application Server 8.1, 8.2 and 9.1 (see http://developers.sun.com/).
Apache Ant 1.6.5 or above is required to perform the deployment on JBoss Application Server. This tool is freely available on http://ant.apache.org/.
If you want to use Natural for Ajax with Natural for Mainframes, the following must be installed:
Natural for Mainframes Version 4.2.3 or above, and
the Natural Web I/O Interface server.
For detailed information, see:
the Installation documentation which is provided with Natural for Mainframes;
the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for Mainframes.
If you want to use Natural for Ajax with Natural for UNIX, the following must be installed:
Natural for UNIX Version 6.3.1 or above, and
the Natural Web I/O Interface daemon.
For detailed information, see:
the Installation documentation which is provided for Natural for UNIX;
the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for UNIX.
If you want to use Natural for Ajax with Natural for Windows, the following must be installed:
Natural for Windows Version 6.3.3 or above, and
the Natural Web I/O Interface server (which is implemented as a service).
For detailed information, see:
the Installation documentation which is provided for Natural for Windows;
the section Installing and Configuring the Natural Web I/O Interface Server in the version of the Natural Web I/O Interface documentation which is provided for Natural for Windows.
If you want to use the Natural parameters
DC
and
DTFORM
in a Natural for
Ajax application, the following versions are required:
Natural for Mainframes Version 4.2.5 or above,
Natural for UNIX Version 6.3.5 or above,
Natural for Windows Version 6.3.5 or above.
If you want to use the workplace example mentioned in Application Designer Workplace Framework, the following versions are required:
Natural for Mainframes Version 4.2.6 or above,
Natural for UNIX Version 6.3.6 or above,
Natural for Windows Version 6.3.6 or above.
If you want to use the example on control variables mentioned in
XCIDATADEF - Data
Definition or the Natural system variable
*CURS-FIELD
in a
Natural for Ajax application, the following versions are required:
Natural for Mainframes Version 4.2.6 or above,
Natural for UNIX Version 6.3.7 or above,
Natural for Windows Version 6.3.7 or above.
The following development servers support the remote development of Natural for Ajax applications:
Natural Development Server for Mainframes Version 2.2.3 or above.
Natural Development Server for UNIX Version 2.2.3 or above.
Natural Development Server for Windows Version 2.2.4 or above.
The following development clients support the remote development of Natural for Ajax applications:
Natural for Windows (Natural Studio) Version 6.3.1 or above.
Natural for Eclipse Version 3.2.1 or above.
NaturalONE Version 8.1 or above.
Supported browsers in this version are:
Internet Explorer 6.0 through 8.0.
Mozilla Firefox 3.0 through 3.5.
Important:
Cookies and JavaScript must be enabled in the
browser.
A valid license key file is required during the installation. The license key file is an XML file which is usually supplied along with the product. Alternatively, you can obtain a license key file from Software AG via your local distributor.
Only one version of the Natural Web I/O Interface client or one version of Natural for Ajax can be installed on the same JBoss Application Server.
You can either install the Natural Web I/O Interface client or Natural for Ajax on the same JBoss Application Server, not both.
It is assumed that <jboss> is the directory of your JBoss Application Server installation.
The following topics are covered below:
To install Natural for Ajax
Install Apache Ant (you need Apache Ant to deploy Natural for Ajax to the JBoss Application Server; see the Prerequisities above for the required version number):
Download and unzip Apache Ant (from http://ant.apache.org/) into an installation directory of your choice. Avoid a directory name that contains blanks.
Let the environment variable
ANT_HOME
point to the directory
<ant> (where
<ant> is the directory of
your Ant installation).
Add
<ant>/bin to your
PATH
environment variable.
Deploy Natural for Ajax to JBoss Application Server:
Copy the Natural for Ajax distributables to a directory on a disk drive.
In the directory that contains the Natural for Ajax distributables, there is an Ant script named jbossdeploy.xml. Edit this script and change the setting
<property name="jbosshome" value=""/>
to
<property name="jbosshome" value="<jboss>"/>
where <jboss> is your JBoss Application Server installation directory.
Important:
Take care to use forward slashes (also on Windows) when
specifying the directory path.
Execute the script jbossdeploy.xml by entering the following command:
ant -f jbossdeploy.xml
Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.
Copy the license file into the directory <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/cis/licensekey.
Edit the file <jboss>/server/default/deploy/jbossjca-service.xml and change the setting
<!-- Enable connection close debug monitoring --> <attribute name="Debug">true</attribute>
to
<!-- Enable connection close debug monitoring --> <attribute name="Debug">false</attribute>
JBoss Application Server 4.0.5 only: Edit the file <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/WEB-INF/web.xml and uncomment the section
<!-- Uncomment the next lines, in case the configuration tool is installed on a JBOSS 4.0.5.GA <listener> <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class> </listener> -->
so that it looks as follows:
<listener> <listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class> </listener>
Important:
For JBoss Application Server 4.2, you must not remove this
comment.
Start JBoss Application Server.
To update Natural for Ajax
Shut down JBoss Application Server.
Deploy Natural for Ajax to JBoss Application Server:
Copy the Natural for Ajax distributables to a directory on a disk drive.
In the directory that contains the Natural for Ajax distributables, there is an Ant script named jbossdeploy.xml. Edit this script and change the setting
<property name="jbosshome" value=""/>
to
<property name="jbosshome" value="<jboss>"/>
where <jboss> is your JBoss Application Server installation directory.
Important:
Take care to use forward slashes (also on Windows) when
specifying the directory path.
In order to upgrade an existing Natural for Ajax 1.2.<n> installation to version 8.1<m>, execute the script jbossdeploy.xml by entering the following command:
ant -f jbossdeploy.xml upgrade
Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.
In order to update an existing Natural for Ajax 8.1.<n> installation to the newest update package (8.1<m>), execute the script jbossdeploy.xml by entering the following command:
ant -f jbossdeploy.xml redeploy
Wait for the message "BUILD SUCCESSFUL". This indicates that the deployment was successful.
Copy the Natural for Ajax 8.1 license file into the directory <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/cis/licensekey.
The update installation creates two backup directories, backup and backupsys, in the JBoss Application Server installation directory. These directories contain a backup of the user project directories and some configuration files. Should the update installation fail for some reason, these directories can be used to restore the the backed up user data in a fresh installation. After a successful update installation, these directories can be removed.
Make sure that the file <jboss>/server/default/deploy/jbossjca-service.xml contains the same settings as described for a first-time installation.
JBoss Application Server 4.0.5 only: Make sure that the file <jboss>/server/default/deploy/njx<nn>.ear/cisnatural.war/WEB-INF/web.xml contains the same settings as described for a first-time installation.
Regenerate the HTML pages of the projects that you have created with an earlier release of Natural for Ajax. For each project to regenerate, execute the script jbossdeploy.xml by entering the following command:
ant -f jbossdeploy.xml regenerate -Dnjxproj=<projectname>
Wait for the message "BUILD SUCCESSFUL". This indicates that the generation was successful.
Start JBoss Application Server.
Natural for Ajax is installed using the Administration Console of Sun Java System Application Server.
The following is assumed:
<host> is the name of the machine on which the application server is installed.
<port> is the name of the port where the application server is installed. In a default installation, this is port 8080.
<adminport> is the name of the port where the Administration Console is installed. In a default installation, this is port 4848.
<sunas> is the path to the directory in which the application server is installed. In a default installation on Windows, this is C:/Sun/AppServer.
The following topics are covered below:
To install Natural for Ajax
Edit the file <sunas>/domains/domain1/config/server.policy and add the following settings:
// Allow Application Designer to create an own class loader grant { permission java.lang.RuntimePermission "createClassLoader"; }; // Allow Application Designer to modify its own project directories grant { permission java.io.FilePermission "${com.sun.aas.instanceRoot}${/}applications${/}j2ee-apps${/}njx<nn>${/}cisnatural_war${/}-", "read,write,delete"; }; // Enable the Java Logging API grant { permission java.util.logging.LoggingPermission "control"; };
Important:
If you do not enable the Java Logging API, the resource
adapter will not start and Natural for Ajax will therefore be
inoperative.
Start the application server.
Open your web browser and enter the following URL:
http://<host>:<adminport>
This opens the Administration Console.
Deploy the resource adapter njx<nn>ra.rar:
Open the tree node Applications > Connector Modules.
Choose Deploy.
Select njx<nn>ra.rar as the package file to be uploaded to the application server.
Choose Next. "njx<nn>ra" is automatically included as the application name.
Choose Finish.
Define the JNDI name for the resource adapter:
Open the tree node Resources> Connectors >Connector Connection Pools.
Choose New.
Enter "NatPool" (the name is arbitrary) as the name.
Select njx<nn>ra as the resource adapter.
Each connection to a Natural host results in a new connection being made. Since each user requires a unique host session, connection pooling cannot be used. Therefore, you should make sure there are enough sessions for your users. The default maximum number is "32".
Choose Next.
Choose Next.
Choose Finish.
Open the tree node Resources> Connectors >Connector Resources.
Choose New.
Enter "eis/NaturalUnicodeRA" as the JNDI name.
Select NatPool (or whatever name you specified previously) as the pool name.
Choose OK.
Deploy the enterprise application njx<nn>.ear:
Open the tree node Applications > Enterprise Applications.
Choose Deploy.
Select njx<nn>.ear as the file to upload.
Choose Next.
Choose OK. The deployment may take several minutes.
Copy the license file into the directory <sunas>/domains/domain1/applications/j2ee-apps/njx<nn>/cisnatural_war/cis/licensekey (you have to create the directory if it does not yet exist).
Restart the application server.
To update Natural for Ajax
Shut down the application server.
Create a backup copy of your sessions.xml file, which is located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nn>/cisnatural_war/WEB-INF.
Create a backup copy of your license file, which is located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nn>/cisnatural_war/cis/licensekey.
Create backup copies of all modified configuration files, which are located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nn>/cisnatural_war/cis/config.
Create backup copies of previously created projects, which are located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nn>/cisnatural_war.
Start the application server.
Start a web browser and enter the following URL:
http://<host>:<adminport>
This opens the Administration Console.
Undeploy the resource adapter njx<nn>ra.rar.
Undeploy the enterprise application njx<nn>.ear.
Deploy the new version of Natural for Ajax as in a first-time installation.
Shut down the application server.
Restore the files that you have backed up in steps 2, 3, 4 and 5.
Start the application server.
Start a web browser and enter the following URL:
http://<host>:<port>/cisnatural/index.html
This opens the Application Designer development workplace.
In the Development Tools node of the navigation frame, choose Layout Manager.
For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the
menu, choose .It is assumed that http://<host>:<port> is the URL of your application server.
To verify the installation
Enter the following URL in your web browser:
http://<host>:<port>/cisnatural/index.html
This opens the Application Designer development workplace.
Enter the following URL in your web browser:
http://<host>:<port>/cisnatural/servlet/StartCISPage?PAGEURL=/cisnatural/NatLogon.html
This opens the Natural logon page. The installation is now complete.