About JavaServer Pages (JSPs)

JavaServer Pages (JSP) provide a simple programming method to display and dynamically update content on a Web page. JSPs are converted to servlets behind the scenes so coding of a JSP is simpler than coding for a servlet. JSPs combine HTML, JavaScript, and Java code.

The following topics are discussed:

Introduction to JSPs

This introduction presents a baseline of how these methods, pages, and programs all relate to one another.

Whereas HTML is basically a document display format, JSPs provide the processing power that lets you create complex client/server applications for the Web and include dynamic substitutions within an HTML page.

JSP is an extension to the Java servlet technology from Sun, but is much different from ordinary Java in that JSPs are dynamically compiled and interpreted on the JSP-enabled application server. With Java servlets, you need a pre-compilation step, where you compile the text into bytecode which makes it more compact, faster to download and faster to interpret. Then the bytecode needs to be compiled and deployed. With JSP, the text of the Java code is interpreted and deployed immediately in one step. You can edit JSPs in pure text and instantly see the changes in the Web browser, just as you can with pure HTML.

In ENOVIA Live Collaboration, JSPs may be stored in the database as page objects or on disk. They are delivered through HTTP in response to the browser. JSPs directly call the business object interface of the ENOVIA Studio Customization Toolkit, using that interface to leverage RMI (Remote Method Invocation), which allows software components stored in the network to be run remotely.

JSPs can also include fragments from other page objects for reusable content. There are many reusable pieces in pure HTML that need to be referred to in multiple pages in an application: the navigation bar, parts of the action bar, the background image, the pieces of table definition that help organize the menu items, and so on. The fragments of HTML can be broken up into separate JSPs, and an include technique can be used to dynamically include the page objects that are needed. In this way, a change to an individual component, for example the navigation bar, can be made in a single resource and the whole application will respond because they are all using that shared fragment. This methodology provides the ability to dynamically model and change the look and feel of applications.

JSP Processing

This section illustrates the processing that occurs when a JSP is requested from a browser.

Each numbered point is described below.




  1. A browser requests the URL for a JSP, such as http://HOSTNAME:PORT/enovia/eServiceLogin.jsp.
  2. The Web server (WebLogic, IBM HTTP, Apache, IIS) recognizes the .jsp extension in the URL, identifying the request as a JavaServer Page which must be handled by the JSP engine.
  3. The Web server forwards the request to the application server (Jrun, WebLogic, WebSphere), which manages the JSP translator and servlet engine.
  4. The page is translated into a Java source file and then compiled into a servlet class file. The compilation and translation phase only occurs when the JSP is first called (and the server finds no corresponding class files for the JSP) or when the source JSP changes.
  5. The servlet engine converts the browser request into a HTTPServletRequest Java object, which is passed to the servlet along with an HTTPServletResponse object that is used to send the response back to the browser.
  6. The servlet then generates the HTML-only response to the browser, including any static HTML included in the JSP and any dynamic content generated by the servlet processing. If you view the source of a JSP from your browser, you will see only HTML content. All Java and Javascript has been converted to static HTML.

This sample JSP demonstrates this process:

1 
<%-- HelloENOVIA.jsp -- displays "Hello ENOVIA Client Appliction!"
2 
--%>
3 
<HTML>
4 
    <HEAD>
5 
   <TITLE>Hello ENOVIA!</TITLE>
6 
    </HEAD>
7 
    <BODY>
8 
   <h1>Hello ENOVIA Client Appliation!</h1>
9 
    </BODY>
10 
</HTML>
11 
<%@inlcude file = "ServletInfo.html"%

Lines 1 and 2 are hidden JSP comments. These comments are ignored by the compiler and therefore do not appear in the HTML source in the browser.

Lines 3 through 10 contain standard HTML to produce the title and main text.

Line 11 uses an include directive to include the ServletInfo.html page. The ServletInfo.html contains only two lines to make up the same footer information displayed in the sample servlet:

<hr>
<p>HelloENOVIAServlet version 1.0</p>

The output for the JSP looks the same as the servlet output.



The HTML source for the JSP contains only HTML code. All Java and Javascript is replaced with static HTML. Also notice the hidden comments are not included. 

<HTML>
    <HEAD>
       <TITLE>Hello ENOVIA!</TITLE>
    </HEAD>
    <BODY>
       <h1>Hello ENOVIA Client Application!</h1>
    </BODY>
</HTML>
<hr>
<p>HelloENOVIAServlet version 1.0</p>

Another way to produce the same output using JSP is to call the Hello ENOVIA servlet from a JSP:

<%-- HelloENOVIA1.jsp   -- displays "Hello ENOVIA Client 
Application" by calling the Hello ENOVIA servlet--%>
<html>
<!-- Forward to a servlet using jsp forward statement-->
<jsp:forward page="/servlet/HelloENOVIAServlet" />
</html>

JSP Access

This section describes how to access a JSP.

To access the JSP file, place the file, including any associated resource files, within the doc root directory structure of your Web server. Then request the URL for the JSP. For example, if the HelloENOVIA.jsp file is located in a directory called "Example" in the doc root, the URL would be: WEB_SERVER_DOC_ROOT/Example/HelloENOVIA.jsp.

Custom JSP Filter

The ENOVIA Live Collaboration Server contains a filter class that allows requests from ENOVIA products to check for a prefixed file name for custom JSP pages.

You can store custom resources (JSP, HTML, and image files) with prefixed filenames to prevent them from being overwritten on subsequent application installs. You can even define multiple prefixes in order to keep various customization, accelerator, or integration files easy to identify.

You can implement a custom directory to store custom files; however, when using custom directories, there are certain jsp directives that will result in run-time (versus compile time) errors if the relative pathing is not correct. Therefore, ENOVIA recommends that you use custom prefixes instead of a custom directory.

Implementing the custom JSP filter involves simple changes to the web.xml file for your application server's WAR file. Refer to the Live Collaboration BPS Installation Guide for details.

Storing Custom Data

You can store custom data or key/value pairs on the Java Context object in an application tier JSP or executable.

This custom data is then available on the server and in JPOs. The Context object (matrix.db.Context) allows programs to share the transactional context of the launching thread. For example, you could store custom data that includes a user's login site location on a JSP and have it available in JPOs.

Custom data stored in a frame context is not available from the parent context associated with that frame context via the application server session id. Custom data stored in a parent context is not available from any existing frame contexts associated with that parent context but will however, be available from any new frame context created under that parent context. Additionally, there are methods available under FrameworkServlet that enable JSPs to store custom data in the main context from which ALL frame contexts are derived.

Refer to the Javadocs for the classes and methods used in storing custom data.

About Writing JSPs

This section contains guidelines for writing JSPs for ENOVIA or custom applications.

The following topics are discussed:


Use Built-In Parameters to Make Pages Reusable

The dynamic user interface components automatically append a number of parameters to URLs.

For example, the parameters emxSuiteDirectory, objectId, and ParentOID are all passed automatically. For a list of automatically-appended parameters, see Parameters Automatically Passed to URLs.

It is important that when JSPs are written to be pop-ups (even if they are called from custom pages initially) that they use these automatically-appended URL parameters and do not invent new ones. That way, when you call a custom page from one of the configurable pages (emxTable.jsp, emxTree.jsp), you do not have to make changes.

It is also important not to pass in data that you can get from the automatically-appended parameters. Passing extra data creates pages that cannot be used from a configurable page.

Standard Error Handling

This section describes the error handling mechanisms used for the configurable components.

Whenever an exception or context-specific error happens in a JSP, an error message displays as a JavaScript popup alert message box. If there are multiple errors within the page, all error messages are collected by the error object and displayed to user.

To achieve this, an Error Object class called FrameworkException is instantiated for every JSP. This class is part of the com.matrixone.framework.util package. The error object instance name is emxNavErrorObject. The instantiation of the object is done at the top include file, emxNavigatorTopErrorInclude.jsp. The error object is used in the processing page for adding the error messages and finally used at the bottom include page, emxNavigatorBottomErrorInclude.jsp, for displaying any error message. This bottom include page also has the MQL Notice Include file, emxMQLNotice.jsp, which alerts any MQL error message that occurs during the processing.

The Error object emxNavErrorObject has the request scope, so the new error object is available to every request. Hence the object is destroyed from memory after displaying the page.

When the error/exception occurs, the page can call the emxNavErrorObject object method addMessage() (on the class FrameworkException).

emxNavErrorObject.addMessage("ERROR TEXT MESSAGE?.");

Multiple error messages can be added to the error object and it maintains a list of messages within the error object. At the end of the page, the list of error messages is collected from the error object and displayed to the user in a single message box.

JSP Layout for Error Handling

Every JSP page that implements this error handling approach should have the following page layout.



Error Handling in the Same Request Scope

Every JSP page that implements error handling with the emxNavErrorObject must include the Top and Bottom Error Include files given in this section.

These are the top and bottom error include files:


  • emxNavigatorTopErrorInclude.jsp
  • emxNavigatorBottomErrorInclude.jsp

All the processing Java code within the JSP page (including jsp:forward and jsp:include) will be in the try.. catch.. finally block. If an error occurs in the processing code, an appropriate error message can be added to the error object using the addMessage() method. The addMessage method can be called within the page just after getting the error message or within the finally block.

The following sample skeleton code shows the syntax and method for implementing the error message. The instance name of the error handling class FrameworkException is emxNavErrorObject, which is instantiated in the Top Include.

// JSP code?
String emxErrorString = "";
try {
?
?
    // Access check
    ?..
    ?..
emxNavErrorObject.addMessage("User does not have access to this object..");
?..
?..
} catch ( Exception e) {
?..
?..
  emxErrorString = (ex.toString()).trim();
} finally {
emxNavErrorObject.addMessage(emxErrorString);
}

Error Handling Not in the Same Request Scope

If an error occurrs in a pure processing page that is not within the same request scope of the referring page, you can set a session attribute to implement error handling.

When there is an error message in the processing page that needs to be displayed to the user, set a session attribute with name error.message with the value assigned to the ERROR TEXT to be displayed. For example:

session..setAttribute("ERROR TEXT MESSAGE?.");

If the JSP that displays subsequent to the processing page has implemented the error handling approach with emxNavErrorObject, the session error message set in the session displays. This subsequent JSP page must follow the JSP layout given in JSP Layout for Error Handling.

Reset Context Limitation

The Context.resetContext method should NOT be the first server call in a new JSP. It must be preceded by ANY server call with the new frame context such as the one in the example in this section.

MQLCommand.executeCommand(ctx, "print context").

To allow multi-threaded JSPs (for example, JSPs representing multi-frame browser pages), ENOVIA Live Collaboration creates a distinct frame context for each frame in each JSP. Each frame context is associated with the parent context via the application server session id. They are kept unique by appending "mxXXXXXX" to that session id.

It is critical for ENOVIA Live Collaboration to distinguish these different frame context objects to avoid operations performed simultaneously on multiple threads from interfering with each other. However, it is also important to correctly associate each of these frame contexts with the correct parent context to guarantee correct access checking against the business model.

Any other server call (as the first call on a page) will associate the frame context correctly with the parent, so a subsequent call to Context.resetContext will recognize the business administrative status, and allow the reset to a different context.

Best Practices for Working with JSPs

This concept presents best practices for writing JSP pages.

The following topics are discussed:


Capturing Exceptions

Capture the exception in JSP and add to emxNavErrorObject. Make sure all the Java code is in a try-catch block. The catch block must use the emxNavErrorObject so that the page shows up an alert message on any error condition.

For example:

try {

} catch (Exception ex) {

     if (ex.toString()!=null && ex.toString().length()>0) 
{emxNavErrorObject.addMessage(ex.toString());}

} finally }

    // Add cleanup statements if required like object close, 
cleanup session, etc.

}

Applies: JSP

Forward Tags

Remove response.sendRedirect() calls to JSP forward tags, or to a form submit. They fail in an SSO environment.

Applies to: JSP

getPersons() Method

Storing data in a HttpSession or static member variables of a JSP requires careful planning. For example, you might write a JSP to display a list of users in a select field using the matrix.db.Person.getPersons() method every time the page is displayed. If the installation has many users, a large number of objects that exist for a short period of time are created. This can strain Java garbage collection. A better solution is to retrieve the list once, keep it in a static member variable, and refresh it every so often.

Restrictions

Do not write Java code with business logic inside JSP pages. Put the business logic and major Java processing in Bean code. Call the bean methods from the JSP.

Applies to: JSP