ABSTRACT

The recently released Netscape Application Server (NAS) enables you to write enterprise-scale, mission-critical, reliable web applications. However, there are times when you'll want to interract with NAS "AppLogic" services from your workgroup applications. This technote will show you how to communicate with NAS from server side JavaScript (SSJS) using LiveConnect. A basic explanation, source, and a downloadable example will demonstrate how to send values between SSJS and an NAS AppLogic.

This technote will demonstrate how to call a Netscape Application Server (NAS) AppLogic from server-side JavaScript (SSJS).  NAS AppLogics are services which are coded in Java or C++ and run within a multi-threaded NAS process.  The list below describes one of the best ways to provide a migration path to move your SSJS application over to NAS, or simply take advantage of NAS features from within your SSJS application.

1. Separate your JavaScript logic from your html pages - put as much of your JavaScript code into a JS library (.js file) as you can.  Call the library functions from your HTML pages rather than putting the code inline with the page.  This separates your business logic and backend processing from the HTML pages that you will present to the user.
2. Create an AppLogic that performs the functionality you need.  (An AppLogic is a service that runs on NAS and performs some functionality - enforcing business rules, communicating with backend databases and mainframes, and interracting with other servers [like messaging or directory servers], etc.).
3. Recode the proper JavaScript library function to call the applogic you created in the previous step (a code example is provided below).

The following example will demonstrate how to call an AppLogic from server side JavaScript.  The SSJS application (ssjs2nas.html) calls a JavaScript function (in the ssjs2nas.js file).  The JavaScript function uses LiveConnect to call a Java class (and pass a string value) which in turn interacts with an NAS AppLogic ("Simple.class").  The string value passed to the AppLogic is modified and passed back to SSJS where it is displayed.  This is a very basic example to demonstrate how to pass values between SSJS and NAS.  To run this sample application (or one like it), you must install a Netscape Application Server.  You should also install the Netscape Application Builder (the development tool).

The following is a diagram that shows how server-side JavaScript communicates with an AppLogic (AL):
 

As you can see, the SSJS application uses LiveConnect to call the Application Server's Open Client Library (OCL) and communicate with an AppLogic running on the Application Server.  A string value from an HTML form in the SSJS application is passed to the AppLogic, which then concatenates the string value to another string and passes the result back to the SSJS application.  The first time this program executes, it is quite slow - because the Enterprise Server must locate and run the Java class, and the Application Server must startup the appropriate AppLogic.  Subsequent calls to the app are remarkably faster - because the Java classes are already in the server's memory.

The next diagram is a more detailed one - note that JavaScript in the HTML document ssjs2nas.html (which is part of an SSJS application) calls a JavaScript function in ssjs2nas.js (also part of an SSJS application) which in turn calls a Java Class in ssjs2nas.class, which uses the OCL to communicate with the AppLogic Simple.class running on the Netscape Application Server.  This may look a bit complicated - but it's pretty straightforward when you create it - the SSJS application simply calls a Java class which in turn calls an AppLogic.  Your business logic should be placed in the JavaScript library (.js file) or preferrably an AppLogic, and your data access should be handled by an AppLogic.

The following HTML document contains a form.  When a value has been entered in the input field fieldValue the form is submitted (to itself - ssjs2nas.html).   The callAppLogic() function residing in ssjs2nas.js is then called.
 

The callAppLogic() function (shown below) uses LiveConnect to execute methods of a Java class found in the Package Packages.ssjs2nas (ssjs2nas.class).  The methods allow the SSJS function to create a NAS client object, form a connection with the NAS server running on "fortress.company.com", pass a string value (request.fieldValue) to an AppLogic, and receive a string back from the AppLogic.

The callAppLogic() function shown above first creates a client object and stores it in a JavaScript variable.  Next, the function creates a connection object and stores it in a JavaScript variable.  The callAppLogic() function then executes a Java method called getValues().  The Java getValues() function uses the connection object (conn) to execute the NAS newRequest() method - passing the GUID for the AppLogic it wants to communicate with.  The AppLogic will simply return a string value.

When calling the getValues() Java method, we send in our connection object (conn), GUID, and the field value from our HTML form (request.fieldValue which we've placed in the variable ssjsString).
 
 

The getValues() Java method in turn calls the AppLogic using the NAS newRequest() method, passing it the GUID value received from JavaScript (The GUID is simply a 128 bit "Global Unique ID" which identifies a specific AppLogic on NAS).
 
 

The other values passed to the NAS newRequest() method are two IValList objects (valIn, valOut).  These objects contain an array of name/value pairs that you can set using the setValString(name, value) method and get using the getValString(name) method.  We use the IValList object valIn (the second parameter) to pass in the field value from our form to the AppLogic.  We later use the IValList object valOut (the third parameter) to read the string value set by the AppLogic.

Lastly, the connection is dropped, the client object is dropped, and the string returned by the AppLogic is displayed by SSJS.

The AppLogic "Simple.class" gets the input value from the IValList object valIn, concatenates it to a string, and returns the resulting string value to ssjs2nas.class.  Even though the "execute()" method of our AppLogic below does not show two IValList objects as input parameters, they are nevertheless available in that method.
 

Remember, valIn contains all of the values we want to pass to the AppLogic, and valOut contains all of the values we want to get from our AppLogic.  So we grab the value associated with the name "inString" (in the IValList object valIn), add it to the string "The value received by the AppLogic was " and place the resulting string into valOut as "outString".  (Thus, valOut now contains a property called "outString" and an associated string value.)

In ssjs2nas.class we grab the value associated with the name "outString" and pass that value (which is a string value) back to JavaScript.  The "callAppLogic()" function in ssjs2nas.js then writes out the string value and the user sees the value on the resulting HTML document returned by the Enterprise Server.

The "execute" method in class Simple simply takes the input parameter "inString", concatenates it to the string "The value received by the AppLogic was" and returns the resulting string.  The portion of code under "// Return HTML result" gets returned if the AppLogic is called via an HTML document using the <GX></GX> tags.  Otherwise, that portion of code is ignored.  The AppLogic knows if it was called directly using the OCL or indirectly via a web browser and the AppLogic returns values accordingly.

We have thus shown you how to communicate with an AppLogic running on the Netscape Application Server.  This may seem a bit complex and confusing - but it's relatively straightforward.  By calling NAS AppLogics from your SSJS application you can extend the functionality of SSJS and take advantage of the robust features of NAS.  This also helps you get more familiar with NAS without having to code an entire application from scratch - you can thus learn how to use NAS at your own pace.

To Install and Run the Sample Application, please do the following:

1. Download the Sample Application (UNIX, Win32)
2. Setup the included applogic (in the "applogic" directory) in your Netscape Application Server
3. Revise ssjs2nas.bat or ssjs2nas - enter correct directory name where ssjs2nas.class file will be placed.  It should be placed in the "local-classes" subdirectory (because that is in the server's classpath by default - so the server will be able to find the class file).
4. Execute "ssjs2nas.bat" (on Win32) or "ssjs2nas" on UNIX.
5. Add "nas" as an SSJS application in the Application Manager for your Netscape Web Server.

Name:           nas
Web File Path:  fully_qualified_path_to_.web_file
Default Page:   ssjs2nas.html
Initial Page:
DB Connections:
External Libs:
Client Object:  client-cookie
6. Run the application

Note:  If you would like to compile the Java file included with this distribution, please do the following:

    Copy the KOCLJDK11.jar file (distributed with NAS/NAB) to a directory in your server's classpath like:
    "<server-root>/plugins/java/local-classes"
    Ensure that this file is in your classpath statement - several "kivasoft" classes are required for the Java to compile and execute properly.

TN-SSJS-01-9804

---

Related Readings:

• Frequently Asked Questions: Find the answers to your questions on Internet technologies.
• Documentation: A library of technical information.
• Developer Central: Collections of developer resources organized by Internet technology areas.

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use