javolution.lang

Class Configurable<T>

java.lang.Object

javolution.lang.Configurable<T>

Direct Known Subclasses:

LocalContext.Parameter

public abstract class Configurable<T>
extends Object

An element which is configurable without presupposing how the configuration is done.

Does your class need to know or has to assume that the configuration is coming from system properties ??

The response is obviously NO !

Let's compare the following examples:

 class Document {
     private static final Font FONT
         = Font.decode(System.getProperty("pkg.Document#FONT") != null ?
             System.getProperty("FONT") : "Arial-BOLD-18");
 }

With the following:

 class Document {
     public static final Configurable<Font> FONT = new Configurable<Font>() {
         @Override
         protected Font getDefault() { 
             new Font("Arial", Font.BOLD, 18);
         }
     };
 }

Not only the second example is cleaner, but the actual configuration data can come from anywhere, from system properties (if property defined), OSGi Configuration Admin service, another bundle, etc. Low level code does not need to know.

Configurables may perform any logic upon initialization or update. Users are notified of configuration events through the OSGi Configurable.Listener service.

 class Index {
     // Holds the number of unique preallocated instances (default {@code 1024}).  
     public static final Configurable<Integer> UNIQUE = new Configurable<Integer>() {
         @Override
         protected Integer getDefault() { 
             return 1024;
         }
         @Override
         protected Integer initialized(Integer value) {
             return MathLib.min(value, 65536); // Hard-limiting
         }
         @Override
         protected Integer reconfigured(Integer oldCount, Integer newCount) {
             throw new UnsupportedOperationException("Unicity reconfiguration not supported."); 
         }               
     }
 }

Version:

6.0, July 21, 2013

Author:

Jean-Marie Dautelle

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Configurable.Listener Services to be published by any one interested in being informed of configurable changes.

Field Summary

Fields

Modifier and Type	Field and Description
static SecurityContext.Permission<Configurable<?>>	RECONFIGURE_PERMISSION Holds the general permission to reconfigure configurable instances (action "reconfigure").

Constructor Summary

Constructors

Constructor and Description
Configurable() Creates a new configurable.

Method Summary

Methods

Modifier and Type	Method and Description
T	get() Returns this configurable value.
protected abstract T	getDefault() Returns this configurable default value (always different from null).
String	getName() Returns this configurable name.
SecurityContext.Permission<Configurable<T>>	getReconfigurePermission() Returns the permission to configure this instance.
protected T	initialized(T value) This methods is called when the configurable is initialized.
protected T	parse(String str) Parses the specified text to return the corresponding value.
T	reconfigure(T newValue) Reconfigures this instance with the specified value if authorized by the SecurityContext.
protected T	reconfigured(T oldValue, T newValue) This methods is called when the configurable is reconfigured.

Methods inherited from class java.lang.Object

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

Field Detail

RECONFIGURE_PERMISSION

public static SecurityContext.Permission<Configurable<?>> RECONFIGURE_PERMISSION

Holds the general permission to reconfigure configurable instances (action "reconfigure"). Whether or not that permission is granted depends on the current SecurityContext. It is possible that the general permission to reconfigure a configurable is granted but revoked for a specific instance. Also, the general permission to reconfigure a configurable may be revoked but granted only for a specific instance.

Constructor Detail

Configurable

public Configurable()

Creates a new configurable. If a system property exist for this configurable's name, the the parsed value of the property supersedes the default value of this configurable. For example, running the JVM with the option -Djavolution.context.ConcurrentContext#CONCURRENCY=0 disables concurrency support.

Method Detail

get

public T get()

Returns this configurable value.

getName

public String getName()

Returns this configurable name. By convention, the name of the configurable is the name of the static field holding the configurable (e.g. "javolution.context.ConcurrentContext#CONCURRENCY"). This method should be overridden if the enclosing class needs to be impervious to obfuscation or if the enclosing class defines multiple configurable fields.

Throws:

UnsupportedOperationException - if the enclosing class has multiple configurable static fields.

getReconfigurePermission

public SecurityContext.Permission<Configurable<T>> getReconfigurePermission()

Returns the permission to configure this instance.

reconfigure

public T reconfigure(T newValue)

Reconfigures this instance with the specified value if authorized by the SecurityContext. This method returns the actual new value which may be different from the requested new value (see reconfigured(Object, Object)).

Parameters:

newValue - the requested new value.

Returns:

the actual new value.

Throws:

SecurityException - if the permission to reconfigure this configurable is not granted.

UnsupportedOperationException - if this configurable does not support dynamic reconfiguration.

getDefault

protected abstract T getDefault()

Returns this configurable default value (always different from null).

initialized

protected T initialized(T value)

This methods is called when the configurable is initialized. Developers may override this method to perform any initialization logic (e.g. input validation).

Parameters:

value - the requested value for this configurable.

Returns:

the actual value of this configurable.

parse

protected T parse(String str)

Parses the specified text to return the corresponding value. This method is used to initialize this configurable from system properties. The default implementation uses the TextContext to retrieve the text format (based on DefaultTextFormat class annotation).

reconfigured

protected T reconfigured(T oldValue,
             T newValue)

This methods is called when the configurable is reconfigured. Developers may override this method to perform any reconfiguration logic (e.g. hard limiting values).

Parameters:

oldValue - the old value.

newValue - the requested new value.

Returns:

the actual new value of this configurable.

Throws:

UnsupportedOperationException - if this configurable does not support dynamic reconfiguration.