com.ibm.lang

Class ThreadProperties

java.lang.Object

com.ibm.lang.ThreadProperties

public final class ThreadProperties
extends java.lang.Object

The ThreadProperties class provides methods to store, retrieve and remove properties specific to a thread or a thread group. The properties are stored in a property map. Each key and its corresponding value in the property map is a string. The properties of a particular thread are the union of thread properties and its thread group properties, with thread properties taking priority if properties are set for the thread and its thread group.

ThreadProperties may be used to effect the behavior of APIs invoked by the thread.

Socket KeepAlive Properties

Key	Description of Associated Value
KEEPALIVE_IDLE_TIME	Number of seconds of idle time on a socket after which TCP sends a keepalive probe to check if the socket connection is active.
KEEPALIVE_PROBE_COUNT	Maximum number of keepalive probes to be sent to validate if the socket connection is active.
KEEPALIVE_INTERVAL_TIME	Interval of time in seconds between sending the keepalive probes.

When these properties are set, each java.net.Socket that is created by this thread is configured with java.net.Socket.setKeepAlive(true) and com.ibm.net.SocketUtils.configureKeepAlive(this, SocketKeepAliveParameters) with the thread properties specified. Enabling the keepalive and configuring the keepalive properties is supported only for TCP/IP sockets created via the java.net.Socket public constructors. Support for the keepalive properties varies by platform. Any property that is not configurable on a per-socket basis on the current operating system will be ignored.

e.g. To enable keepalive and set the keepalive idle time to 1 hour, keepalive probe count to 10 and keepalive interval to 20 seconds for all sockets created by the current thread

 ...

 ThreadProperties.setProperty(ThreadProperties.KEEPALIVE_IDLE_TIME, "3600");
 ThreadProperties.setProperty(ThreadProperties.KEEPALIVE_PROBE_COUNT, "10");
 ThreadProperties.setProperty(ThreadProperties.KEEPALIVE_INTERVAL_TIME, "20");
 ... 
 

e.g. To retrieve the keepalive idle time set for the current thread

 ...
 int idleTime = Integer.parseInt(ThreadProperties.getProperty
 (ThreadProperties.KEEPALIVE_IDLE_TIME));
 ...
 

e.g. To retrieve all the properties set for a specific thread group

 ...
 ThreadGroup threadGroup = new ThreadGroup ("Group 1");
 Thread sampleThread = new Thread(threadGroup, new SampleThread());
 sampleThread.start();

 //
 public void run() {

 // Get all the properties set for the threadGroup
 ThreadPropertyMap properties = ThreadProperties.getProperties(threadGroup);
 Iterate through the properties and print the values
 Iterator iter = propsMap.keySet().iterator();
 while(iter.hasNext()) {
     String prop_name = (String)iter.next();
      System.out.println("Value of " + prop_name + " = " + propsMap.get(prop_name));
 }
 ...
 

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	KEEPALIVE_IDLE_TIME Defines the length of idle time in seconds on the socket until a keepalive probe is sent.
static java.lang.String	KEEPALIVE_INTERVAL_TIME Defines the length of interval of time in seconds between sending the keepalive probes.
static java.lang.String	KEEPALIVE_PROBE_COUNT Defines the maximum number of keepalive probes that can be sent to validate if the socket connection is active.

Constructor Summary

Constructors

Constructor and Description
ThreadProperties()

Method Summary

Methods

Modifier and Type	Method and Description
static void	clearProperties() Removes all the properties of this thread and associated propertymap.
static void	clearProperties(java.lang.ThreadGroup threadGroup) Removes all the properties of the specified thread group and associated propertymap.
static java.lang.String	clearProperty(java.lang.String key) Removes this thread's property indicated by the specified key.
static java.lang.String	clearProperty(java.lang.ThreadGroup threadGroup, java.lang.String key) Removes specified thread group's property indicated by the specified key.
static ThreadPropertyMap	getProperties() Returns a copy of all the properties set for this thread or its thread group.
static ThreadPropertyMap	getProperties(boolean checkThreadGroup) Returns a copy of all the properties set for this thread or its thread group.
static ThreadPropertyMap	getProperties(java.lang.ThreadGroup threadGroup) Returns a copy of all the properties set for the specified thread group.
static java.lang.String	getProperty(java.lang.String key) Gets the property indicated by the specified key set for this thread or its thread group.
static java.lang.String	getProperty(java.lang.String key, boolean checkThreadGroup) Gets the property indicated by the specified key set for this thread or its thread group.
static java.lang.String	getProperty(java.lang.ThreadGroup threadGroup, java.lang.String key) Gets the specified thread group's property indicated by the specified key.
static void	setProperties(java.lang.ThreadGroup threadGroup, ThreadPropertyMap properties) Sets the specified thread group's properties to the ThreadPropertyMap argument.
static void	setProperties(ThreadPropertyMap properties) Sets the current thread's properties to the ThreadPropertyMap argument.
static java.lang.String	setProperty(java.lang.String key, java.lang.String value) Sets the current thread's property indicated by the specified key.
static java.lang.String	setProperty(java.lang.ThreadGroup threadGroup, java.lang.String key, java.lang.String value) Sets the specified thread group's property indicated by the specified key.

Methods inherited from class java.lang.Object

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

Field Detail

KEEPALIVE_IDLE_TIME

public static final java.lang.String KEEPALIVE_IDLE_TIME

Defines the length of idle time in seconds on the socket until a keepalive probe is sent. This thread property is interpreted as an integer and is used to set the com.ibm.net.SocketKeepAliveParameters.setIdleTime(int) value for java.net.Socket created by this thread.

KEEPALIVE_PROBE_COUNT

public static final java.lang.String KEEPALIVE_PROBE_COUNT

Defines the maximum number of keepalive probes that can be sent to validate if the socket connection is active. This thread property is interpreted as an integer and is used to set the com.ibm.net.SocketKeepAliveParameters.setProbeCount(int) value for java.net.Socket created by this thread.

KEEPALIVE_INTERVAL_TIME

public static final java.lang.String KEEPALIVE_INTERVAL_TIME

Defines the length of interval of time in seconds between sending the keepalive probes. This thread property is interpreted as an integer and is used to set the com.ibm.net.SocketKeepAliveParameters.setIntervalTime(int) value for all java.net.Socket created by this thread.

Constructor Detail

ThreadProperties

public ThreadProperties()

Method Detail

getProperty

public static java.lang.String getProperty(java.lang.String key)

Gets the property indicated by the specified key set for this thread or its thread group.

Searches for the property with the specified key in this thread's property map. If the key is not found in this thread's property map, its thread group's property map is searched. The method returns null if the property is not found.

First, if there is a security manager, its checkPropertyAccess method is called with the key as its argument. This may result in a SecurityException.

Parameters:

key - the name of the property.

Returns:

the string value of the property, or null if there is no property with that key.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertyAccess method doesn't allow access to the specified thread property.

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

setProperty(java.lang.String, java.lang.String), SecurityException, SecurityManager.checkPropertyAccess(java.lang.String), getProperties()

getProperty

public static java.lang.String getProperty(java.lang.String key,
                           boolean checkThreadGroup)

Gets the property indicated by the specified key set for this thread or its thread group.

Searches for the property with the specified key in this thread's property map. If the key is not found in this thread's property map, its thread group's property map is searched, only if checkThreadGroup is true. The method returns null if the property is not found.

First, if there is a security manager, its checkPropertyAccess method is called with the key as its argument. This may result in a SecurityException.

Parameters:

key - the name of the property.

checkThreadGroup - indicates if property has to be searched in thread group or not.

Returns:

the string value of the property, or null if there is no property with that key.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertyAccess method doesn't allow access to the specified property.

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

setProperty(java.lang.String, java.lang.String), SecurityException, SecurityManager.checkPropertyAccess(java.lang.String), getProperties()

getProperties

public static ThreadPropertyMap getProperties()

Returns a copy of all the properties set for this thread or its thread group.

Checks if the properties are set for this thread. If the properties are not set for this thread, then checks if the properties are set for its thread group. The method returns null if no properties are set for this thread or its thread group.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Returns:

the properties or null if there are no properties set for this thread or its thread group.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

See Also:

setProperties(com.ibm.lang.ThreadPropertyMap), SecurityException, SecurityManager.checkPropertiesAccess(), ThreadPropertyMap

getProperties

public static ThreadPropertyMap getProperties(boolean checkThreadGroup)

Returns a copy of all the properties set for this thread or its thread group.

Checks if the properties are set for this thread. If the properties are not set for this thread, then checks if the properties are set for its thread group, only if checkThreadGroup is true. The method returns null if no properties are set for this thread or its thread group.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Parameters:

checkThreadGroup - indicates if property has to be searched in thread group or not.

Returns:

the properties or null if there are no properties set for this thread or its thread group.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

See Also:

setProperties(com.ibm.lang.ThreadPropertyMap), SecurityException, SecurityManager.checkPropertiesAccess(), ThreadPropertyMap

setProperty

public static java.lang.String setProperty(java.lang.String key,
                           java.lang.String value)

Sets the current thread's property indicated by the specified key.

First, if a security manager exists, its SecurityManager.checkPermission method is called with a PropertyPermission(key, "write") permission. This may result in a SecurityException being thrown. If no exception is thrown, the specified property is set to the given value.

If there are no properties for this thread, a property map is first created and specified property is set.

Parameters:

key - the name of the thread property.

value - the value of the thread property.

Returns:

the previous value of the thread property, or null if it did not have one.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPermission method doesn't allow setting of the specified property.

java.lang.NullPointerException - if key or value is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

getProperty(java.lang.String), getProperty(java.lang.String), getProperty(java.lang.String, boolean), PropertyPermission, SecurityManager.checkPermission(java.security.Permission)

setProperties

public static void setProperties(ThreadPropertyMap properties)

Sets the current thread's properties to the ThreadPropertyMap argument.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Parameters:

properties - the new thread properties.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

java.lang.NullPointerException - if properties is null.

See Also:

getProperties(), SecurityException, SecurityManager.checkPropertiesAccess(), ThreadPropertyMap

clearProperty

public static java.lang.String clearProperty(java.lang.String key)

Removes this thread's property indicated by the specified key.

First, if a security manager exists, its SecurityManager.checkPermission method is called with a PropertyPermission(key, "write") permission. This may result in a SecurityException being thrown. If no exception is thrown, the specified property is removed.

Parameters:

key - the name of the thread property to be removed.

Returns:

the previous string value of the thread property, or null if there was no property with that key.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertyAccess method doesn't allow access to the specified thread property.

java.lang.NullPointerException - if key is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

getProperty(java.lang.String), setProperty(java.lang.String, java.lang.String), SecurityException, SecurityManager.checkPropertiesAccess()

clearProperties

public static void clearProperties()

Removes all the properties of this thread and associated propertymap.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

See Also:

SecurityException, SecurityManager.checkPropertiesAccess()

getProperty

public static java.lang.String getProperty(java.lang.ThreadGroup threadGroup,
                           java.lang.String key)

Gets the specified thread group's property indicated by the specified key.

First, if there is a security manager, its checkPropertyAccess method is called with the key as its argument. This may result in a SecurityException.

Parameters:

threadGroup - the thread group.

key - the name of the thread group property.

Returns:

the string value of the thread group property, or null if there is no property with that key.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertyAccess method doesn't allow access to the specified thread property.

java.lang.NullPointerException - if threadGroup or key is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

setProperty(java.lang.String, java.lang.String), SecurityException, SecurityManager.checkPropertyAccess(java.lang.String), getProperties()

getProperties

public static ThreadPropertyMap getProperties(java.lang.ThreadGroup threadGroup)

Returns a copy of all the properties set for the specified thread group. The method returns null if no properties are set for the specified thread group.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Parameters:

threadGroup - the thread group.

Returns:

the properties or null if there are no properties set for the specified thread group.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

java.lang.NullPointerException - if threadGroup is null.

See Also:

setProperties(com.ibm.lang.ThreadPropertyMap), SecurityException, SecurityManager.checkPropertiesAccess(), ThreadPropertyMap

setProperty

public static java.lang.String setProperty(java.lang.ThreadGroup threadGroup,
                           java.lang.String key,
                           java.lang.String value)

Sets the specified thread group's property indicated by the specified key.

First, if a security manager exists, its SecurityManager.checkPermission method is called with a PropertyPermission(key, "write") permission. This may result in a SecurityException being thrown. If no exception is thrown, the specified property is set to the given value.

If there are no properties for the specified thread group, a property map is first created and specified property is set.

Parameters:

threadGroup - the thread group.

key - the name of the thread group property.

value - the value of the thread group property.

Returns:

the previous value of the thread group property, or null if it did not have one.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPermission method doesn't allow setting of the specified property.

java.lang.NullPointerException - if threadGroup, key or value is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

getProperty(java.lang.String), getProperty(java.lang.String), getProperty(java.lang.String, boolean), PropertyPermission, SecurityManager.checkPermission(java.security.Permission)

setProperties

public static void setProperties(java.lang.ThreadGroup threadGroup,
                 ThreadPropertyMap properties)

Sets the specified thread group's properties to the ThreadPropertyMap argument.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Parameters:

threadGroup - the thread group.

properties - the new thread group properties.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread group properties.

java.lang.NullPointerException - if threadGroup or properties is null.

See Also:

getProperties(), ThreadPropertyMap, SecurityException, SecurityManager.checkPropertiesAccess(), ThreadPropertyMap

clearProperty

public static java.lang.String clearProperty(java.lang.ThreadGroup threadGroup,
                             java.lang.String key)

Removes specified thread group's property indicated by the specified key.

First, if a security manager exists, its SecurityManager.checkPermission method is called with a PropertyPermission(key, "write") permission. This may result in a SecurityException being thrown. If no exception is thrown, the specified property is removed.

Parameters:

threadGroup - the thread group.

key - the name of the thread group property to be removed.

Returns:

the previous string value of the thread group property, or null if there was no property with that key.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertyAccess method doesn't allow access to the specified thread property.

java.lang.NullPointerException - if threadGroup or key is null.

java.lang.IllegalArgumentException - if key is empty.

See Also:

getProperty(java.lang.String), setProperty(java.lang.String, java.lang.String), SecurityException, SecurityManager.checkPropertiesAccess()

clearProperties

public static void clearProperties(java.lang.ThreadGroup threadGroup)

Removes all the properties of the specified thread group and associated propertymap.

First, if there is a security manager, its checkPropertiesAccess method is called with no arguments. This may result in a security exception.

Parameters:

threadGroup - the thread group.

Throws:

java.lang.SecurityException - if a security manager exists and its checkPropertiesAccess method doesn't allow access to the thread properties.

java.lang.NullPointerException - if threadGroup is null.

See Also:

SecurityException, SecurityManager.checkPropertiesAccess()