sos.db
Class ReadOnlyManager

java.lang.Object
  sos.db.ReadOnlyManager

public class ReadOnlyManager
extends java.lang.Object

A class that keeps track of whether or not a method is read-only. It is initialized with the status of the mutable Java Collection interfaces. Clients may register additional methods by invoking setMethodStatus.

This class uses one of five values to classify a method:

READ_ONLY: The method is guaranteed never to modify its receiver. The following are examples of read-only methods:

• java.lang.Object.equals
• java.util.Collection.size
• java.util.Set.contains

DEFERRED_WRITE: The method itself is guaranteed never to modify its receiver, but the client may modify it indirectly through the returned object. Consider the following code:

   List prefix = list.subList( 0, 4 );
   prefix.clear();

The subList method never modifies the list; however, subList returns a view of the original list, and modifying the sub-list in fact modifies the original list. The following are other examples:

• java.util.Collection.iterator
• java.util.Map.entrySet
• java.util.TreeSet.tail

WRITE: The method may modify the receiver. The following are examples of write methods:

• java.util.Iterator.remove
• java.util.List.clear

WRITE_NO_GARBAGE: The method may modify the receiver, but never in a way that can cause a reachable database object to become unreachable. This may aid the garbage collector in knowing when to perform a collection. The following are examples:

• java.util.Collection.add
• java.util.Collection.addAll

UNKNOWN: The method's status is not known.

Since:

1.0

See Also:

AbstractTransactionPolicy

Field Summary

static int	DEFERRED_WRITE A constant that indicates that a method does not modify its receiver except possibly through the returned object.
static int	READ_ONLY A constant that indicates that a method does not modify its receiver.
static int	UNKNOWN A constant that indicates that a method's read-only status is unknown.
static int	WRITE A constant that indicates that a method may modify its receiver.
static int	WRITE_NO_GARBAGE A constant that indicates a method may modify its receiver in such a way that no reachable object becomes unreachable.

Method Summary

static int	getMethodStatus(java.lang.reflect.Method method) Returns the registered read-only status of the specified method.
static int	getMethodStatus(java.lang.String methodString) Returns the registered read-only status of the method with the specified descriptor.
static void	setMethodStatus(java.lang.Class declaringClass, java.lang.String methodName, java.lang.Class[] parameterTypes, int status) Sets the read-only status of the method with the given declaring class, name, and parameter types.
static void	setMethodStatus(java.lang.reflect.Method method, int status) Sets the read-only status of the specified method.
static void	setMethodStatus(java.lang.String methodString, int status) Sets the read-only status of the method with the given descriptor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UNKNOWN

public static final int UNKNOWN

A constant that indicates that a method's read-only status is unknown.

See Also:

Constant Field Values

READ_ONLY

public static final int READ_ONLY

A constant that indicates that a method does not modify its receiver.

See Also:

Constant Field Values

DEFERRED_WRITE

public static final int DEFERRED_WRITE

A constant that indicates that a method does not modify its receiver except possibly through the returned object.

See Also:

Constant Field Values

WRITE

public static final int WRITE

A constant that indicates that a method may modify its receiver.

See Also:

Constant Field Values

WRITE_NO_GARBAGE

public static final int WRITE_NO_GARBAGE

A constant that indicates a method may modify its receiver in such a way that no reachable object becomes unreachable.

Since:

2.0

See Also:

Constant Field Values

Method Detail

getMethodStatus

public static int getMethodStatus(java.lang.reflect.Method method)

Returns the registered read-only status of the specified method.

Parameters:

method - the method for which the status is requested

Returns:

the registered status of method--one of READ_ONLY, DEFERRED_WRITE_VALUE, WRITE, and UNKNOWN

Throws:

java.lang.NullPointerException - if method is null

See Also:

setMethodStatus(Method,int)

getMethodStatus

public static int getMethodStatus(java.lang.String methodString)

Returns the registered read-only status of the method with the specified descriptor. See setMethodStatus(String,int) for the format of the descriptor.

Parameters:

methodString - descriptor specifying the method

Returns:

the registered status of method--one of READ_ONLY, DEFERRED_WRITE_VALUE, WRITE, and UNKNOWN

Throws:

java.lang.NullPointerException - if methodString is null

Since:

2.0

See Also:

setMethodStatus(String,int)

setMethodStatus

public static void setMethodStatus(java.lang.reflect.Method method,
                                   int status)

Sets the read-only status of the specified method.

Parameters:

method - the method for which to specify the status

status - the read-only status of the method--one of READ_ONLY, DEFERRED_WRITE, WRITE, and UNKNOWN

Throws:

java.lang.IllegalArgumentException - if status is not an acceptable value

java.lang.NullPointerException - if method is null

See Also:

setMethodStatus(Class,String,Class[],int), setMethodStatus(String,int)

setMethodStatus

public static void setMethodStatus(java.lang.Class declaringClass,
                                   java.lang.String methodName,
                                   java.lang.Class[] parameterTypes,
                                   int status)
                            throws java.lang.NoSuchMethodException

Sets the read-only status of the method with the given declaring class, name, and parameter types.

Parameters:

declaringClass - the class that contains the method to classify

methodName - name of the method to classify

parameterTypes - argument types of the method to classify

status - the read-only status of the method--one of READ_ONLY, DEFERRED_WRITE, WRITE, and UNKNOWN

Throws:

java.lang.IllegalArgumentException - if status is not an acceptable value

java.lang.NoSuchMethodException - if a method with name methodName and parameter types parameterTypes is not found in class declaringClass

java.lang.NullPointerException - if declaringClass or methodName is null

See Also:

setMethodStatus(Method,int), setMethodStatus(String,int)

setMethodStatus

public static void setMethodStatus(java.lang.String methodString,
                                   int status)

Sets the read-only status of the method with the given descriptor. The descriptor should be in the form

 
  .(,,...,

 where class_name is the result of calling getName
 on the method's declaring class object, method_name
 is the result of calling getName on the method object,
 and parameter_k is the result of calling
 getCanonicalName on the kth parameter's class object.


 Clients should use this overloaded version if they wish
 to initialize a method's status without triggering the loading
 of the class containing the method.



Parameters:
methodString - descriptor specifying the method
status - the read-only status of the method--one of
   READ_ONLY, DEFERRED_WRITE, WRITE, and UNKNOWN
Throws:
java.lang.IllegalArgumentException - if status is not an acceptable value
java.lang.NullPointerException - if methodString is null
Since:
  
2.0
See Also:
setMethodStatus(Class,String,Class[],int), 
setMethodStatus(Method,int)