Chapter 2   Session API




Session API Overview

---

The Session Application Programming Interface (API) defines applications to access session services provided by the Session Server. Java applications can access session services by using the Java Session API.

Additionally, the Session API provides an XML DTD to define the format for data streams to provide to the server session process and to define the format for data streams coming from the server session process. These formats are required to access session functions from non-Java client software, but can be transparently integrated into Java applications, as shown in the sample code in this chapter.

Implementing the Session API

---

Using the Session API

A session represents a connection between a client and a server where information is exchanged between the two entities. It is critical to maintain state information between the two entities to prevent unauthorized clients from accessing resources in the iPlanet Portal Server platform. A state object, called a cookie, is used to maintain and store state information.

Sessions are a general mechanism which server side connections can use to both store and retrieve information on the client side of the connection. The addition of a simple, persistent, client-side state significantly extends the capabilities of Web-based client/server applications. A server, when returning an HTTP object to a client, may also send a piece of state information which the client will store. Included in that state object is a description of the session credentials for which that state is valid. Any future HTTP requests made by the client which fall in that range will include a transmittal of the current value of the state object from the client back to the server.

There are two main types of sessions:

• User session

• Application session

A user session is associated with a user. An application session is associated with an application without the context of a user. The session type (user or application) property in a session is used to distinguish a user session from an application session.

A session is created when a user or an application authenticates itself successfully. The authentication service creates a new session in the iPlanet Portal Server platform through a private interface provided by the Session Service. An active session at minimum has the following properties:

Session ID	A random string generated by session service to uniquely identify the session. The string is carried in every HTTP/HTTPS request headers as cookies.
Session type	Whether this session is a user session or an application session.
Client id	The user id or the application id depending on the session type.
Domain name	The domain name of the user/application they belong to. It is used to distinguish users/applications of the same name. The domain name property is where the user's profile is located in the role tree.
Creation time	When the session is created.
Access time	The latest time the session is accessed.
Session state	Whether the session is valid or invalid.

Figure 2-1    Session Service Block Diagram

The Session API can access session services provided by the iPlanet Portal Server software by using over-the-wire protocol. This protocol consists of the transport protocol and detailed message format in order to access iPlanet Portal Server services. A Java implementation of this over-the-wire protocol is also provided so that the transport protocol and message format details can be hidden from Java application developers.

Non-Java applications access session services by using HTTP/HTTPS transport protocol and XML messages defined by the Session API to communicate with the session server.

Session API Transport Protocol

As HTTP is the main communication protocol in the iPlanet Portal Server platform and well defined, there is no need to invent a new syntax and semantics for the transport of the Session API, it is a natural choice to use HTTP as the transport protocol to access those session services for the Session API.

Session API Message Format

All session requests, responses, and events are encoded to XML. The main advantage to use XML encoded message is that non-java applications can access session services of the iPlanet Portal Server platform by using the required transport protocol and XML message format described in this section.

The following are the main session requests used by the Session API:

• Get a session

• Get all valid sessions. (Protected by policy)

• Destroy a session. (Protected by policy)

• Logout a session

• Add a listener on a session

• Set session properties

A session can be destroyed by an administrator. It will also be destroyed based on the session idle time and session maximum duration time.

Idle time	The difference between the current time and the last access time.
Session duration time	The difference between the current time and the session creation time.

The default maximum session idle time and duration time shall be in the Session Service Profile, which makes it possible to assign different maximum idle and duration time to different users and applications by overwriting those values in the users profiles and applications profiles respectively.

Session API Classes and Interfaces

The classes that can be included in the Java implementation automatically handle communication and data transfer with the iPlanet Portal Server product.

Session Class	This class represents a session. It contains session related information such as session id, session type (user/application), client id (user id or application id), session creation time, latest session access time, and session state. It also allows applications to add listener for session events.
SessionID Class	This class is used by applications to identify individual iPlanet Portal Server sessions. The SessionID information includes the originating domain of the user.
SessionEvent Class	This class represents a session event. It contains the session object for the event, event type, event time, and event specific information corresponding to the event type if any.
SessionListener Interface	This is an interface which needs to be implemented by applications in order to receive session events.

Sample Session Code

The following code sample illustrates how a new application might use the Session API.

Instructions for using the HelloServlet

1. Set IPS_BASE to the iPlanet Portal Server installation directory.

2. Change directory and make the file as shown in the following example:

   # cd $IPS_BASE/SUNWips/sample/api # make

3. Copy the class files to the appropriate directory on the portal server under:

   $IPS_BASE/SUNWips/lib

   For example, all class files would be copied to:

   $IPS_BASE/SUNWips/lib/com/iplanet/portalserver/api

4. Modify the web server configuration.

   The web server configuration files are in the directory:

   $IPS_BASE/netscape/server4/https-servername/config

   where servername is the FQDN of the portal server.

5. Add the following line to the web server servlets.properties file:

   servlet.helloservlet.code=com.iplanet.portalserver.api.HelloServlet

   Replace the package and servlet names with the names that were chosen for this HelloServlet.

6. Add the following line to the web server rules.properties file:

   /helloservlet=helloservlet

7. As root, Import iwtHelloServlet.xml using ipsadmin, as shown in the following example:

   # $IPS_BASE/SUNWips/bin/ipsadmin -import iwtHelloServlet.xml

8. copy file iwtHelloServlet.properties to $IPS_BASE/SUNWips/locale directory

9. Restart the iPlanet Portal Server server.

   # /etc/init.d/ipsserver start

10. Test the servlet by logging in to the iPlanet Portal Server desktop and entering the following URL:

    https://gateway/http://server:8080/helloservlet

where gateway and server are replaced by the names of the gateway and server.

Import the iPlanet Portal Server Classes

At a minimum, the Java client application should import the iPlanet Portal Server Profile, logging, and Session classes, as shown here.

Code Example 2-1 Importing iPlanet Portal Server Classes

---

// @(#)HelloServlet.java 1.1 00/04/20 Copyright (c) 1999 Sun Microsystems, Inc., All rights reserved.

package com.iplanet.portalserver.api;

import java.io.*;

import java.util.*;

import javax.servlet.*;

import javax.servlet.http.*;

import java.util.Vector;

import com.iplanet.portalserver.session.*;

import com.iplanet.portalserver.profile.*;

import com.iplanet.portalserver.logging.*;

import com.iplanet.portalserver.util.*;

While directly access the classes as needed, importing the logging and session classes will allow better use of the Session functions.

The sections below briefly describe some of the functionality available, but reference the Javadocs online at:

http://yourserver:port/docs/en_US/javadocs

Sample Code

The following code sample illustrates how a new application might use the Session API.

Code Example 2-2 Sample Session API

---

public class HelloServlet extends HttpServlet {

public void doGet(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException {

try {

// Get a session

SessionID sid = new SessionID(req);

Session sess = Session.getSession(sid);

// Validate a session

if (sess.getState(false) != Session.VALID)

return;

// Add a session listener

sess.addSessionListener(new HelloSessionListener());

} catch (SessionException e) {

}

}

class HelloSessionListener implements SessionListener {

public void sessionChanged(SessionEvent e) {

Session sessionEvt = null;

// if the session is still valid, just return

// without doing anything

try {

sessionEvt = e.getSession();

if (sessionEvt.getState(false) == Session.VALID)

return;

else {

// clean up profile before quitting

}

} catch (Exception se) {}

}

}

}