com.sas.servlet.util
Class Util

com.sas.servlet.util.Util

public class Util

Utility methods for use within JSP pages and/or servlets.

The majority of the methods in the Util class deal with sharing objects within the server: stored Connection connections and shared Rocf object factories. There are also generic methods to store session bound data; i.e. data that is associated with the servlet session, as well as global data that has a timeout. This utility class allow you to find Connection/Rocf objects which are stored on and bound to an HTTP session. These objects are automatically stopped when the HTTP session ends. This is done through the BoundConnection and BoundRocf wrapper objects.

Synchronizing Access to Session and Global Data

When using these methods, you should ensure that you prevent simultaneous access to critical sections by wrapping your code in a

 synchronized (getLock()) { ... }
 

block. For example, if you wish to cache some computed result, such as the values from a data table on a SAS server, use:

 synchronized (Util.getLock())
 {
    SimpleTable table = (SimpleTable) Util.getGlobalObject(yourUniqueDataName);
    if (table == null)
        table = ...; // code to populate table here
    Util.putGlobalObject(yourUniqueDataName, table);
 }
 

However, you should be careful that the code within the critical section does not take a long time to execute, since on a server, many other sessions may block on this lock. If the code is potentially time consuming, and it is not an problem to generate the same data twice if multiple threads access it, is to compute the data first, if the global data does not yet exist, then store it in a critical section only if another thread has not already done so:

 SimpleTable table = (SimpleTable) Util.getGlobalObject(yourUniqueDataName);

 if (table == null)
        table = ...; // code to populate table here
 else
    return table;
 synchronized (Util.getLock())
 {
    SimpleTable gTable = (SimpleTable) Util.getGlobalObject(yourUniqueDataName);
    if (gTable == null)
       // no other thread created the data. Save new global data.
       {
          gTable = table;
          Util.putGlobalObject(yourUniqueDataName, gTable);
       }
    else
       // although we computed a table, another thrad did as well
       // and beat us to the punch for storing the global data,
       // so we discard our version and use the global data version.
       table = gTable; // discard
 }
 

Although session based objects have less potential for asynchronous thread contention on shared session data in Util, you should still guard the get/put operations with a synchronized block on getLock() since some servlets may use multiple threads per session.

See Also:

BoundConnection, BoundRocf

Field Summary

static java.lang.String	CONNECTION
static java.lang.String	ROCF

Constructor Summary

Util()

Method Summary

static com.sas.collection.StringCollection	createStringCollection(com.sas.collection.StaticOrderedCollectionInterface model) Creates a copy of the data provided by the model implementing StaticOrderedCollectionInterface.
static com.sas.collection.StringCollection	createStringCollection(com.sas.collection.StaticOrderedCollectionInterface model, boolean sort) Creates a copy of the data provided by the model implementing StaticOrderedCollectionInterface.
static java.lang.String	decodeBase64(java.lang.String s) Decode a base64 encoded string.
static java.lang.String[]	decodeURLParameter(java.lang.String[] value, javax.servlet.http.HttpServletResponse response, javax.servlet.http.HttpServletRequest request) Decodes an ascii string value to the specified character encoding
static java.lang.String[]	decodeURLParameter(java.lang.String[] value, java.lang.String encode) Decodes an ascii string value to the specified character encoding
static java.lang.String	decodeURLParameter(java.lang.String value, javax.servlet.http.HttpServletResponse response, javax.servlet.http.HttpServletRequest request) Decodes an ascii string value to the specified character encoding
static java.lang.String	decodeURLParameter(java.lang.String value, java.lang.String encode) Decodes an ascii string value to the specified character encoding
static com.sas.rmi.Rocf	getClassFactory(javax.servlet.http.HttpServletRequest req) Returns the default webAF class factory.
static com.sas.rmi.Rocf	getClassFactory(javax.servlet.http.HttpServletRequest req, boolean create) Returns the default webAF class factory
static com.sas.rmi.Rocf	getClassFactory(javax.servlet.http.HttpServletRequest req, boolean create, java.lang.String name) Returns the named webAF class factory
static com.sas.rmi.Connection	getConnection(javax.servlet.http.HttpServletRequest req) Returns the session's default webAF connection.
static com.sas.rmi.Connection	getConnection(javax.servlet.http.HttpServletRequest req, boolean create) Returns the session's default webAF connection
static com.sas.rmi.Connection	getConnection(javax.servlet.http.HttpServletRequest req, boolean create, java.lang.String name) Returns the named webAF connection associated with a servlet session.
static java.lang.Object	getGlobalObject(java.lang.String name) Returns the named object from the global object pool or null if the named object does not exist.
static long	getGlobalObjectLastUsedMillis(java.lang.String name) Returns the last time the named object from the global object pool was used.
static java.util.Enumeration	getGlobalObjectNames() Returns an enumeration of all the global object names.
static java.lang.Object	getLock() Return a lock object which may be used as a monitor for critical sections which get and put either session objects or global objects.
static com.sas.collection.hlist.HListInterface	getParametersAsList(javax.servlet.http.HttpServletRequest req) Creates an HList containing all of the request parameters.
static java.lang.Object	getSessionObject(javax.servlet.http.HttpServletRequest req, java.lang.String name) Returns the named object from the session or null if the named object does not exist See also the important discussion above about synchronizing access to session and global data for the proper way to use putSessionObject(HttpServletRequest, String, Object) and getSessionObject
protected static boolean	isEncodingSet(javax.servlet.http.HttpServletRequest request) Checks if characterEncoding is set on the request object.
static java.lang.Object	newInstance(javax.servlet.http.HttpServletRequest req, java.lang.Class c) Creates a new instance of a remote model using the default class factory and connection
static java.lang.Object	newInstance(com.sas.rmi.Rocf rocf, com.sas.rmi.Connection connection, java.lang.Class c) Creates a new instance of a remote model using the class factory and connection given.
static void	putGlobalObject(java.lang.String name, java.lang.Object value) Puts the named object in the global object pool.
static void	putGlobalObject(java.lang.String name, java.lang.Object value, long seconds) Puts the named object in the global object pool.
static void	putSessionObject(javax.servlet.http.HttpServletRequest req, java.lang.String name, java.lang.Object value) Puts the named object in the session.
static java.lang.String	replaceSpecialCharacters(java.lang.String inputString, int browserType) Utility method for replacing special characters (&,$,<,>,',").
static void	resetBeanStringProperties(java.lang.Object bean, javax.servlet.ServletRequest request, java.lang.String properties, boolean alwaysReset, java.lang.String defaultValue) Reset String properties of a bean to a default value.
static void	setClassFactory(javax.servlet.http.HttpServletRequest req, com.sas.rmi.Rocf rocf) Sets the default webAF class factory.
static void	setClassFactory(javax.servlet.http.HttpServletRequest req, com.sas.rmi.Rocf rocf, java.lang.String name) Sets the named webAF class factory associated with the session.
static void	setConnection(javax.servlet.http.HttpServletRequest req, com.sas.rmi.Connection con) Sets the default webAF connection
static void	setConnection(javax.servlet.http.HttpServletRequest req, com.sas.rmi.Connection con, java.lang.String name) Sets the named webAF connection.

Field Detail

ROCF

public static final java.lang.String ROCF

See Also:

Constant Field Values

CONNECTION

public static final java.lang.String CONNECTION

See Also:

Constant Field Values

Constructor Detail

Util

public Util()

Method Detail

getClassFactory

public static com.sas.rmi.Rocf getClassFactory(javax.servlet.http.HttpServletRequest req)
                                        throws javax.servlet.ServletException,
                                               java.io.IOException

Returns the default webAF class factory. If the factory does not exist one will be created.

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The object factory will be bound to this req's session.

Returns:

The class factory or null if one has not yet been created

Throws:

javax.servlet.ServletException - thrown if some type of servlet error occurs

java.io.IOException - thrown if some type of I/O error occurs

getClassFactory

public static com.sas.rmi.Rocf getClassFactory(javax.servlet.http.HttpServletRequest req,
                                               boolean create)
                                        throws javax.servlet.ServletException,
                                               java.io.IOException

Returns the default webAF class factory

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The object factory will be bound to this req's session.

create - Set to true if the object should be created

Returns:

The class factory or null if one has not yet been created

Throws:

javax.servlet.ServletException - thrown if some type of servlet error occurs

java.io.IOException

getClassFactory

public static com.sas.rmi.Rocf getClassFactory(javax.servlet.http.HttpServletRequest req,
                                               boolean create,
                                               java.lang.String name)
                                        throws javax.servlet.ServletException,
                                               java.io.IOException

Returns the named webAF class factory

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The object factory will be bound to this req's session.

create - Set to true if the object should be created

name - The object name

Returns:

The class factory or null if one has not yet been created

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

getLock

public static java.lang.Object getLock()

Return a lock object which may be used as a monitor for critical sections which get and put either session objects or global objects. See Synchronizing Access to Session and Global Data above for more details.

Returns:

an object that may be used for a synchronized block, as in

   java.util.ArrayList data = null;
   synchronized ( Util.getLock() )
   {
     data = (java.util.ArrayList) Util.getGlobalObject("myGlobalData");
     if (data == null)
        {
           data = new java.util.ArrayList()
           Util.putGlobalData(MY_KEY, data);
        }
   }
 

setClassFactory

public static void setClassFactory(javax.servlet.http.HttpServletRequest req,
                                   com.sas.rmi.Rocf rocf)
                            throws javax.servlet.ServletException,
                                   java.io.IOException

Sets the default webAF class factory.

Parameters:

req - The request object. If req is null, this method does nothing.

rocf - The class factory, or null to remove the current value

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

setClassFactory

public static void setClassFactory(javax.servlet.http.HttpServletRequest req,
                                   com.sas.rmi.Rocf rocf,
                                   java.lang.String name)
                            throws javax.servlet.ServletException,
                                   java.io.IOException

Sets the named webAF class factory associated with the session.

Parameters:

req - The request object. If req is null, this method does nothing.

rocf - The class factory, or null to remove the current value

name - The object name

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

getConnection

public static com.sas.rmi.Connection getConnection(javax.servlet.http.HttpServletRequest req)
                                            throws javax.servlet.ServletException,
                                                   java.io.IOException

Returns the session's default webAF connection. If the connection does not exist one will be created.

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The connection will be bound to this req's session.

Returns:

The connection or null if one has not yet been created

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

getConnection

public static com.sas.rmi.Connection getConnection(javax.servlet.http.HttpServletRequest req,
                                                   boolean create)
                                            throws javax.servlet.ServletException,
                                                   java.io.IOException

Returns the session's default webAF connection

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The connection will be bound to this req's session.

create - Set to true if the object should be created

Returns:

The connection or null if one has not yet been created

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

getConnection

public static com.sas.rmi.Connection getConnection(javax.servlet.http.HttpServletRequest req,
                                                   boolean create,
                                                   java.lang.String name)
                                            throws javax.servlet.ServletException,
                                                   java.io.IOException

Returns the named webAF connection associated with a servlet session.

Parameters:

req - The request object. If req is null, this method does nothing and returns null. The connection will be bound to this req's session.

create - Set to true if the object should be created

name - The object name

Returns:

The connection or null if one has not yet been created

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

setConnection

public static void setConnection(javax.servlet.http.HttpServletRequest req,
                                 com.sas.rmi.Connection con)
                          throws javax.servlet.ServletException,
                                 java.io.IOException

Sets the default webAF connection

Parameters:

req - The request object. If req is null, this method does nothing.

con - The connection, or null to remove the current value

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

setConnection

public static void setConnection(javax.servlet.http.HttpServletRequest req,
                                 com.sas.rmi.Connection con,
                                 java.lang.String name)
                          throws javax.servlet.ServletException,
                                 java.io.IOException

Sets the named webAF connection.

Parameters:

req - The request object. If req is null, this method does nothing.

con - The connection, or null to remove the current value

name - The object name

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

newInstance

public static java.lang.Object newInstance(javax.servlet.http.HttpServletRequest req,
                                           java.lang.Class c)
                                    throws javax.servlet.ServletException,
                                           java.io.IOException

Creates a new instance of a remote model using the default class factory and connection

Parameters:

req - The request object

class - The class to create

Returns:

A new instance of the remote object

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

newInstance

public static java.lang.Object newInstance(com.sas.rmi.Rocf rocf,
                                           com.sas.rmi.Connection connection,
                                           java.lang.Class c)
                                    throws javax.servlet.ServletException,
                                           java.io.IOException

Creates a new instance of a remote model using the class factory and connection given. This is just a convenience wrapper to catch remote exceptions and throw the proper ServletException

Parameters:

rocf - The class factory

connection - The connection

class - The class to create

Returns:

A new instance of the remote object

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

java.io.IOException - if some type of I/O error occurs

getSessionObject

public static java.lang.Object getSessionObject(javax.servlet.http.HttpServletRequest req,
                                                java.lang.String name)
                                         throws javax.servlet.ServletException

Returns the named object from the session or null if the named object does not exist

See also the important discussion above about synchronizing access to session and global data for the proper way to use putSessionObject(HttpServletRequest, String, Object) and getSessionObject

Parameters:

req - The request object

name - The name of the object

Returns:

The object from the session

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

See Also:

putSessionObject(HttpServletRequest, String, Object), putGlobalObject(String, Object), putGlobalObject(String, Object, long)

putSessionObject

public static void putSessionObject(javax.servlet.http.HttpServletRequest req,
                                    java.lang.String name,
                                    java.lang.Object value)
                             throws javax.servlet.ServletException

Puts the named object in the session. A value of null will cause the named object to be removed

See also the important discussion above about synchronizing access to session and global data for the proper way to use putSessionObject and getSessionObject(HttpServletRequest, String)

Parameters:

req - The request object

name - The name of the object

value - The value of the object

Throws:

javax.servlet.ServletException - if some type of servlet error occurs

See Also:

getSessionObject(HttpServletRequest,String)

getGlobalObject

public static java.lang.Object getGlobalObject(java.lang.String name)

Returns the named object from the global object pool or null if the named object does not exist. Global objects are available to any servlet running in the same virtual machine

See also the important discussion above about synchronizing access to session and global data for the proper way to use putGlobalObject(String, Object) and getGLobalObject(String)

Parameters:

name - The name of the object

Returns:

The object from the global pool

See Also:

putGlobalObject(String, Object, long), putGlobalObject(String, Object)

getGlobalObjectLastUsedMillis

public static long getGlobalObjectLastUsedMillis(java.lang.String name)

Returns the last time the named object from the global object pool was used.

Parameters:

name - The name of the object

Returns:

The last time the object was used in milliseconds

getGlobalObjectNames

public static java.util.Enumeration getGlobalObjectNames()

Returns an enumeration of all the global object names.

Returns:

An enumeration of the object names

putGlobalObject

public static void putGlobalObject(java.lang.String name,
                                   java.lang.Object value)

Puts the named object in the global object pool. Global objects are available to any servlet running in the same virtual machine. The object will timeout and be destroyed 30 minutes after its last use.

See also the important discussion above about synchronizing access to session and global data for the proper way to use putGlobalObject and getGlobalObject(String)

Parameters:

name - The name of the object

value - The value of the object, or null to remove the object from the pool

See Also:

getGlobalObject(String), putGlobalObject(String,Object,long)

putGlobalObject

public static void putGlobalObject(java.lang.String name,
                                   java.lang.Object value,
                                   long seconds)

Puts the named object in the global object pool. Global objects are available to any servlet running in the same virtual machine. The object will timeout after the given number of seconds after its last use and be destroyed.

See also the important discussion above about synchronizing access to session and global data for the proper way to use putGlobalObject and getGlobalObject(String)

Parameters:

name - The name of the object

value - The value of the object, or null to remove the object from

timeoutSeconds - The number of seconds before timing out the pool

See Also:

getGlobalObject(java.lang.String)

createStringCollection

public static com.sas.collection.StringCollection createStringCollection(com.sas.collection.StaticOrderedCollectionInterface model)

Creates a copy of the data provided by the model implementing StaticOrderedCollectionInterface. This copy can be stored as part of the Session if desired.

Parameters:

model - The model containing the data

Returns:

The new model containing the data

createStringCollection

public static com.sas.collection.StringCollection createStringCollection(com.sas.collection.StaticOrderedCollectionInterface model,
                                                                         boolean sort)

Creates a copy of the data provided by the model implementing StaticOrderedCollectionInterface. This copy can be stored as part of the Session if desired. Setting sort to true will cause the list to be returned in sorted (ascending) order.

Parameters:

model - The model containing the data

sort - true if the data should be sorted

Returns:

The new model containing the data

getParametersAsList

public static com.sas.collection.hlist.HListInterface getParametersAsList(javax.servlet.http.HttpServletRequest req)

Creates an HList containing all of the request parameters. This is useful for passing the request parameters to SCL methods, for example. Single-value parameters will be stored in a StringItem (name-value pair). Multiple-value parameters will be stored as a named ListItem with each value being an unnamed StringItem within the sublist.

For example, the parameters from a simple form with 3 input fields (first name, last name, and favorite colors) might return the list:

Name	Value	Object Type
first	Bugs	StringItem
last	Bunny	StringItem
color	Red	StringItem

Another simple form with 3 input fields, one if which is a list box that allows multiple selections, might return the list:

Name	Value	Object Type
first	Bugs	StringItem
last	Bunny	StringItem
color	(object)	ListItem

With the 'color' list object containing:

Name	Value	Object Type
null	Red	StringItem
null	Green	StringItem
null	Orange	StringItem

Parameters:

request - The HTTP request

Returns:

The list of parameters

decodeBase64

public static java.lang.String decodeBase64(java.lang.String s)

Decode a base64 encoded string.

Parameters:

s - The base64 encoded string

Returns:

The decoded string

resetBeanStringProperties

public static void resetBeanStringProperties(java.lang.Object bean,
                                             javax.servlet.ServletRequest request,
                                             java.lang.String properties,
                                             boolean alwaysReset,
                                             java.lang.String defaultValue)
                                      throws javax.servlet.ServletException

Reset String properties of a bean to a default value.

This method works around a certain documented but often undesirable behavior of the <jsp:setProperty ...> JSP tag. The JSP spec for setProperty says that property set methods are not called when the corresponding servlet request parameters are empty. Thus, if a user blanks out a value on an HTML form, the property will not get set to "". This method provides a way to reset such String properties of a bean to blank.

A sample call is shown below. This call is used to unconditionally reset the properties named title and author to null before invoking <jsp:setProperty>

 <jsp:usBean id="book" scope="session" type="com.unknown.publishing.Book"/>
 <%Util.resetBeanStringProperties(book, null, "author,title", true, null;);%>
 <jsp:setProperty name="book" property="*" />
 

This operation can also be done with JSP snippet code such as the following:

 book.setTitle(""):
 book.setAuthor("");
 

However, a JSP page may not want to unconditionally reset the properties. This is true if the corresponding parameters may not exist in the request (i.e. no title or author servlet parameters), or when it may be expensive to set the property, especially when the <jsp:setProperty ...> code may then turn around and set it to a non-blank value. Thus, the default behvaior of resetBeanStringProperties is to only reset a property if the property is listed in the servlet parameters and if the value there is blank. For example, this call is used to reset the properties named title and author to blank before invoking <jsp:setProperty>, but only if the corresponding servlet request parameters are not blank:

 <jsp:usBean id="book" scope="session" type="com.unknown.publishing.Book" />
 <% Util.resetBeanStringProperties(book, request, "author,title", false, ""); %>
 <jsp:setProperty name="book" property="*" />
 

See the JSP spec for more details on how <jsp:setProperty> works.

Parameters:

bean - A bean whose String properties you wish to reset to blank or null values. This is typically the subject of a following <jsp:setProperty> tag.

request - The servlet request containing the servlet parameters, typically from a HTML form. If null, then all candidate properties are reset.

properties - A String containing a comma separated list of candidate properties, such as "firstName,lastName", to reset. If properties is null or "*", then all writable String properties will be candidates for being reset. Otherwise, only those listed in this String will be candidates.

alwaysReset - controls which candidate properties are actually reset. If true, then all candidate String properties with a write method will be reset. If false, then only those candidate String properties which have blank parameter values in the request are reset.

defaultValue - the value to assign to a property when resetting it. This value is passed to the bean's property write method. Normally, this should be the empty string "", but you can use any other String or null.

Throws:

javax.servlet.ServletException

replaceSpecialCharacters

public static java.lang.String replaceSpecialCharacters(java.lang.String inputString,
                                                        int browserType)

Utility method for replacing special characters (&,$,<,>,',"). Valid values of browserType are ints defined by com.sas.servlet.util.ClientInfo: ClientInfo.WML_UP_BROWSER ClientInfo.WML_OTHER_BROWSER ClientInfo.HDML_BROWSER ClientInfo.HTML_BROWSER

Parameters:

inputString - The String on which to perform the replacements

browserType - The type of browser replaced with.

Returns:

The String with replaced characters

decodeURLParameter

public static java.lang.String decodeURLParameter(java.lang.String value,
                                                  java.lang.String encode)

Decodes an ascii string value to the specified character encoding

Parameters:

value - The string to decode

encode - encode value

Returns:

The decoded value

decodeURLParameter

public static java.lang.String[] decodeURLParameter(java.lang.String[] value,
                                                    java.lang.String encode)

Decodes an ascii string value to the specified character encoding

Parameters:

value - The string(s) to decode

encode - encode value

Returns:

The decoded array value

decodeURLParameter

public static java.lang.String decodeURLParameter(java.lang.String value,
                                                  javax.servlet.http.HttpServletResponse response,
                                                  javax.servlet.http.HttpServletRequest request)

Decodes an ascii string value to the specified character encoding

Parameters:

value - The string to decode

response - The response object

request - The request object

Returns:

The decoded value

decodeURLParameter

public static java.lang.String[] decodeURLParameter(java.lang.String[] value,
                                                    javax.servlet.http.HttpServletResponse response,
                                                    javax.servlet.http.HttpServletRequest request)

Decodes an ascii string value to the specified character encoding

Parameters:

value - The string to decode

response - The response object

request - The request object

Returns:

The decoded value

isEncodingSet

protected static boolean isEncodingSet(javax.servlet.http.HttpServletRequest request)

Checks if characterEncoding is set on the request object.

Parameters:

request - The request object

Returns:

true if character encoding is set on the request; false otherwise