Version 4.2.6 for Mainframes SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT
 —  Natural for Ajax  —

Installation

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.

Prerequisites

The following topics are covered below:

Java

JDK 1.5.0_12 or above is required.

J2EE Server

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.

Apache Ant

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/.

Natural for Mainframes

If you want to use Natural for Ajax with Natural for Mainframes, the following must be installed:

For detailed information, see:

Natural for UNIX

If you want to use Natural for Ajax with Natural for UNIX, the following must be installed:

For detailed information, see:

Natural for Windows

If you want to use Natural for Ajax with Natural for Windows, the following must be installed:

For detailed information, see:

Support for Special Features

If you want to use the Natural parameters DC and DTFORM in a Natural for Ajax application, the following versions are required:

If you want to use the workplace example mentioned in Application Designer Workplace Framework, the following versions are required:

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:

Development Servers

The following development servers support the remote development of Natural for Ajax applications:

Development Clients

The following development clients support the remote development of Natural for Ajax applications:

Browser Prerequisites

Supported browsers in this version are:

Important:
Cookies and JavaScript must be enabled in the browser.

Top of page

License Key File Handling

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.

Top of page

Installing Natural for Ajax on JBoss Application Server

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:

First-time Installation

Start of instruction setTo install Natural for Ajax

  1. 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):

    1. Download and unzip Apache Ant (from http://ant.apache.org/) into an installation directory of your choice. Avoid a directory name that contains blanks.

    2. Let the environment variable ANT_HOME point to the directory <ant> (where <ant> is the directory of your Ant installation).

    3. Add <ant>/bin to your PATH environment variable.

  2. Deploy Natural for Ajax to JBoss Application Server:

    1. Copy the Natural for Ajax distributables to a directory on a disk drive.

    2. 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.

    3. 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.

  3. Copy the license file into the directory <jboss>/server/default/deploy/njx12.ear/cisnatural.war/cis/licensekey.

  4. 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>

  5. JBoss Application Server 4.0.5 only: Edit the file <jboss>/server/default/deploy/njx12.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.

  6. Start JBoss Application Server.

Update Installation

Start of instruction setTo update Natural for Ajax

  1. Shut down JBoss Application Server.

  2. Deploy Natural for Ajax to JBoss Application Server:

    1. Copy the Natural for Ajax distributables to a directory on a disk drive.

    2. 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.

    3. In order to upgrade an existing Natural for Ajax 1.1.1 installation to version 1.2, 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.

    4. In order to update an existing Natural for Ajax 1.2.<n> installation to the newest update package (1.2.<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.

    5. 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.

  3. Make sure that the file <jboss>/server/default/deploy/jbossjca-service.xml contains the same settings as described for a first-time installation.

  4. JBoss Application Server 4.0.5 only: Make sure that the file <jboss>/server/default/deploy/njx12.ear/cisnatural.war/WEB-INF/web.xml contains the same settings as described for a first-time installation.

  5. 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.

  6. Start JBoss Application Server.

Top of page

Installing Natural for Ajax on Sun Java System Application Server

Natural for Ajax is installed using the Adminstration Console of Sun Java System Application Server.

The following is assumed:

The following topics are covered below:

First-time Installation

Start of instruction setTo install Natural for Ajax

  1. 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${/}njx12${/}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.

  2. Start the application server.

  3. Open your web browser and enter the following URL:

    http://<host>:<adminport>

    This opens the Adminstration Console.

  4. Deploy the resource adapter njx12ra.rar:

    1. Open the tree node Applications > Connector Modules.

    2. Choose Deploy.

    3. Select njx12ra.rar as the package file to be uploaded to the application server.

    4. Choose Next. "njx12ra" is automatically included as the application name.

    5. Choose Finish.

  5. Define the JNDI name for the resource adapter:

    1. Open the tree node Resources> Connectors >Connector Connection Pools.

    2. Choose New.

    3. Enter "NatPool" (the name is arbitrary) as the name.

    4. Select njx12ra as the resource adapter.

    5. 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".

    6. Choose Next.

    7. Choose Next.

    8. Choose Finish.

    9. Open the tree node Resources> Connectors >Connector Resources.

    10. Choose New.

    11. Enter "eis/NaturalUnicodeRA" as the JNDI name.

    12. Select NatPool (or whatever name you specified previously) as the pool name.

    13. Choose OK.

  6. Deploy the enterprise application njx12.ear:

    1. Open the tree node Applications > Enterprise Applications.

    2. Choose Deploy.

    3. Select njx12.ear as the file to upload.

    4. Choose Next.

    5. Choose OK. The deployment may take several minutes.

  7. Copy the license file into the directory <sunas>/domains/domain1/applications/j2ee-apps/njx12/cisnatural_war/cis/licensekey (you have to create the directory if it does not yet exist).

  8. Restart the application server.

Update Installation

Start of instruction setTo update Natural for Ajax

  1. Shut down the application server.

  2. Create a backup copy of your sessions.xml file, which is located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nnn>/cisnatural_war/WEB-INF.

  3. Create a backup copy of your license file, which is located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nnn>/cisnatural_war/cis/licensekey.

  4. Create backup copies of all modified configuration files, which are located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nnn>/cisnatural_war/cis/config.

  5. Create backup copies of previously created projects, which are located in <sunas>/domains/domain1/applications/j2ee-apps/njx<nnn>/cisnatural_war.

  6. Start the application server.

  7. Start a web browser and enter the following URL:

    http://<host>:<adminport>

    This opens the Adminstration Console.

  8. Undeploy the resource adapter njx<nnn>ra.rar.

  9. Undeploy the enterprise application njx<nnn>.ear.

  10. Deploy the new version of Natural for Ajax as in a first-time installation.

  11. Shut down the application server.

  12. Restore the files that you have backed up in steps 2, 3, 4 and 5.

  13. Start the application server.

  14. Start a web browser and enter the following URL:

    http://<host>:<port>/cisnatural

    This opens the Application Designer development workplace.

  15. In the Development Tools node of the navigation frame, choose Layout Manager.

  16. For each application project that you have created with an earlier release of Natural for Ajax, select the layout definitions and from the Operations on multiple Items menu, choose (Re)Generate HTML Pages.

Top of page

Verifying the Installation

It is assumed that http://<host>:<port> is the URL of your application server.

Start of instruction setTo verify the installation

  1. Enter the following URL in your web browser:

    http://<host>:<port>/cisnatural

    This opens the Application Designer development workplace.

  2. 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.

Top of page

 www.softwareag.com  Copyright © Software AG 1979-2009. All rights reserved.  SEARCH   INDEX   CONTENTS   |   PDF PAGE   PDF BOOKS   |   HOME   UP   PREV   NEXT