POCMasthead.gif (6305 bytes)

 

Modifying the Sample Servlet for Your Proof-of-Concept



This section explains the included Java Servlet code and files.  It also details those changes you need to make to use this Servlet as a Proof-of-Concept for your specific case.  This document comments on most sections of the Java Servlet, even those that you should not have to change for your Proof-of-Concept.  Those sections that you have to change will be marked as such.

Note that you must define the servlet to WebSphere Application Server.  You must also define properties to pass the location of  machine running your CICS Transaction Gateway, the port used by your CICS Transaction Gateway, the name of your CICS region (server), and the name of the CICS programs to be called for signon and information retrieval.  Follow the directions in The Environment section to define the servlet.

This section assumes you have read the previous sections, and have a general understanding of Java and Java Servlets.

This section assumes you have un-zipped the included file, have have access to the POCServlet.java and POCDataBean.java file.

For directions on preparing the environment and running the supplied Servlet, see the environment section.

Characters like "###1#' were added to the Java program and are referenced in this discussion.  This allows you to quickly go to a particular section of code that is being discussed.  For example, when the import statements are discussed, "###1#" is referenced.  You can then search the Java code for "###1#" and see the code being discussed.


Sections of the Java Servlet Code include: 


Import Statements

This section is marked with "###1#".  The import statements required for this Java Servlet include classes for regular Java classes (those that start with "java"), classes required to write Servlets (those that start with "javax"), and classes required for using the CICS Transaction Gateway (starts with "com.ibm.ctg").

[back]


The Servlet class declaration

This is right above "###2#".  The name of the Servlet is "POCServlet" (case sensitive).  The Servlet is an extension of HTTPServlet.

[back]


Servlet Instance variables

Marked with "###3#". The instance variables are available to every invocation of the doGet() and doPost() methods (the doGet() or doPost() methods are invoked when a web browser makes a GET or POST request).  Since there can be multiple invocations of doGet() and/or doPost() from multiple browsers at the same time (i.e. they are multithreaded), be sure to carefully watch what variables or object references are instance variables (i.e. available to every method invocation at the same time). For example, you may what to control concurrent access to an object by using synchronized methods in that object.

Instance variables were used for items such as the name of the CICS programs to be used, and the name and port number of the CICS Transaction Gateway.  There is also a single object reference for the CICS Transaction Gateway.  This means that all CICS requests will flow through the same object.  This is OK as long as you stay with simple synchronous ECI requests.  If you are doing more complex requests like EPI or extended logical units of work, you will have to keep the state of each request or series of requests in some structure like a hashtable.  When a request comes in from a browser, you will then have to find the browser's state by identifying the browser and searching the hashtable for your object that contains that browser's state information.   This means that this Java Servlet has been coded specifically for simple synchronous ECI requests.

You will need to set servlet properties when you define the servlet to WebSphere to indicate the name of your customer's CICS region (in their cicscli.ini file), the port they are using for the CICS Transaction Gateway, and the location of their CICS Transaction Gateway.

[back]


The init() method

Marked with "###4#.  The init() method is invoked when the Servlet is loaded. You override the init() method to do processing that will be needed for all of the later doGet() and doPost() requests.  If you override the init() method, super.init() should be invoked.  This servlet writes a message to standard out so that you can see when the init method is invoked.   The message written with System.out.println is written to a file by WebSphere Application Server.  Note that, by default, the standard out of WebSphere Application Server Servlets is redirected to a file.  To easily see the output from the System.out.println() statements, you can start the admin console from the administration panels.  You can also temporarily turn on the WebSphere Application Server Console by executing http://your.machine.name/servlet/DebugConsoleServlet.  The stdout and stderr are written to the WEBSPHEREAPP_ROOT\logs directory, and are called jvm_stdout.log and jvm_stderr.log.  These file names can be changed using the admin panels or by modifying property files.

The init() also attempts to connect to the CICS Transaction Gateway.  Each request checks to see if the attempt to connect to the CICS Transaction Gateway was successful, and if the attempt was not successful, an additional attempt will be made.  This means that the servlet will connect to the CICS Transaction Gateway as soon as it is available.  Meanwhile, an appropriate messages will be sent back to the requestor.  The attempts to connect to the CICS Transaction Gateway are made my invoking the connectToGateway() method.

[back]


The connectToGateway() method

Marked with "###5#".  This method attempts a connection to the CICS Transaction Gateway.  If the attempt is successful and if bCheckStatus (an instance variable) is set to true, each server defined to the CICS Client is listed (to the message file, see above), along with the status of each server.

[back]


The displayState() method

Marked with "###6#". This method is used by the connectToGateway() method to display CICS server status.

[back]


The doGet() method

Marked with "###7#".  A Servlet doGet() method is invoke if a Servlet is invoked with no form processing or via a form requesting GET processing.  For this Servlet the doGet() method is invoked when the Servlet is invoked by a direct reference to the Servlet. 

The method checks if there is a connection to the CICS Transaction Gateway.  If none exists, it attempts to establish the connection.  If no connection to the CICS Transaction Gateway can be established, a message is sent to the browser indicating a problem with the CICS Transaction Gateway.  The message that is sent back to the browser is very simple and is probably adequate for a proof-of-concept.   In a production environment, a nicer, more extensive message may be more appropriate.

If a connection to the CICS Transaction Gateway exists (established in this method or before), the session object is referenced (or created if none exists).  If the session object contains an entry for CICSECI.UserName, then the user has previously authenticated.  Note that the WebSphere Application Server mechanism will invalidate session objects if they have not been used for a specified time.  If the user is authenticated, the HTML for user requests is delivered back to the browser.   If the user is not authenticated, a form requesting signon information is sent back to the browser. 

The Servlet is currently written so that the HTML to be sent back to the user is stored in .jsp files.  Click here to see more information on Java Server Pages (JSP).

[back]


The doPost() method

Marked with "###8#".  The doPost() method is invoke via a form requesting POST processing.  This method first establishes output writability to the response object, then establishes a reference to the session object (or creates one of none exists).

If a form requested a logoff, the userid and password are removed from the session object and the signon HTML is sent to the browser. This is at "###9#". Note that the session object was not invalidated when the logoff button is pressed.  This session object could be used for multiple applications, so an invalidation of the session object could affect other applications.

The method then checks to see if the reference to the CICS Transaction Gateway connection is null, if null it attempts a connection and sends out a simple error message if unsuccessful (again, the message is probably fine for a proof-of-concept).  This is at "###10#".

The method then checks (at "###11#") if the session object contains a username (i.e. they have authenticated).  If they have not authenticated, the method assumes this is the signon information.  It takes the userid and password from the form and makes an ECI call to a CICS program to validate the userid/password combination.   If the return from the CICS program is successful, the userid and password are stored in the session object and the HTML for regular requests is sent to the browser..   If the return from the CICS program is not successful, the userid and password are not stored in the session object and the signon form is sent to the browser with an error message.. 

If one of the above conditions has not caused HTML to be sent back to the browser, a regular request is processed which results in taking the form data and making an ECI request to CICS.  Marked with "###12#"

This area of the Servlet is will require changes for your proof-of-concept.  You will have to define the layout of the customer's COMMAREA, and will have to load the values returned in the DataBean,  and will have to construct HTML that will display the returned COMMAREA values.

[back]


The destroy() Method

Marked with "###13#".  The destroy() method is invoked when the Servlet is unloaded.  This method checks to see if the CICS Transaction Gateway object is null.   If it is not null, the method closes the connection to the CICS Transaction Gateway.

[back]


Generated HTML

All HTML to be sent to be sent to the browser in this sample Servlet is stored in Java Server Pages (JSP) (see the JSP documentation to read about the many ways that JSP can be used).

JSP were used so that HTML could be dynamic based on information return from CICS, with no HTML coded in the Servlet. This is done by adding data to a JavaBean in your Servlet, then passing the JavaBean to your JSP.  The JSP then accesses the data in the JavaBean and includes the data in the generated HTML that is to be sent back to the browser. 

To implement this (at '###7#'), the Servlet: 

  • Instanciates the JavaBean that will contain the data to be passed,
  • Sets values in the JavaBean,
  • Indicates the name of the JavaBean to be passed using the setAttribute() method of the HTTP request object, and
  • Uses the callPage() method of the HTTP response object to indicate the JSP to invoke.
The JavaBean that contains the data is in a separate file called POCDataBean.java.

Then, in the JSP, after specifying a /bean tab, to access the data in the bean (properties) you can: 

  • use a JSP scriptlet  (yep, yet another word that ends in let)
  • use a JSP expression 
  • use the <INSERT> tag.
You can see an example of the techniques to access the JavaBean properties in any of the .jsp files included with this sample Servlet.

You will have to change the JSPs to fit your proof-of-concept.

[back]


Last Modified on 01/10/99

[Home]    [Overview]    [Environment]     [Servlets]    [This Servlet]    [Summary]


[ Privacy ][ Legal ][ Search ][ Contact ]