The JPPF configuration API

1 General properties handling

The JPPF configuration properties are accessible at runtime, via a static method call: JPPFConfiguration.getProperties(). This method returns an object of type TypedProperties, which is an extension of java.util.Properties with additional methods to handle properties with primitive values: boolean, int, long, float and double.

Here is a summary of the API provided by TypedProperties:

public class TypedProperties extends Properties {
  // constructors
  public TypedProperties()
  // initialize with existing key/value pairs from a map
  public TypedProperties(Map<Object, Object> map)
  // string properties
  public String getString(String key)
  public String getString(String key, String defValue)
  public TypedProperties setString(String key, String value)
  // int properties
  public int getInt(String key)
  public int getInt(String key, int defValue)
  public TypedProperties setInt(String key, int value)
  // long properties
  public long getLong(String key)
  public long getLong(String key, long defValue)
  public TypedProperties setLong(String key, long value)
  // float properties
  public float getFloat(String key)
  public float getFloat(String key, float defValue)
  public TypedProperties setFloat(String key, float value)
  // double properties
  public double getDouble(String key)
  public double getDouble(String key, double defValue)
  public TypedProperties setDouble(String key, double value)
  // char properties
  public TypedProperties getChar(String key)
  public TypedProperties getChar(String key, char defValue)
  public TypedProperties setChar(String key, char value)
  // boolean properties
  public boolean getBoolean(String key)
  public boolean getBoolean(String key, boolean defValue)
  public TypedProperties setBoolean(String key, boolean value)
  // File properties
  public File getFile(String key)
  public File getFile(String key, File defValue)
  public TypedProperties setFile(String key, File value)
}

As you can see, each getXXX() method has a corresponding method that takes a default value, to be returned if the property is not defined for the specified key. Most of them also have a corresponding fluent setter method, which allows setting multiple properties of diffferent types in a call chain.

It is possible to alter the JPPF configuration, via calls to the setXXX(String, XXX) methods of TypedProperties. If you wish to programmatically change one or more JPPF configuration properties, then it should be done before they are used. For instance, in a client application, it should be done before the JPPF client is initialized, as in this sample code:

// get the configuration
TypedProperties config = JPPFConfiguration.getProperties();
// set the connection properties programmatically
config.setBoolean("jppf.discovery.enabled", false)
  .setString("jppf.drivers", "driver1")
  .setString("driver1.jppf.server.host", "www.myhost.com")
  .setInt("driver1.jppf.server.port", 11111);

// now our configuration will be used
JPPFClient client = new JPPFClient();

2 Predefined JPPF properties

The JPPF properties documented in the Configuration properties reference chapter are also avaialable as instances of the JPPFProperty interface, which is defined as follows:

public interface JPPFProperty<T> extends Serializable {
  // Get the name of this property
  String getName();

  // Get the default value of this property
  T getDefaultValue();

  // Get the aliases for this property, that is, other names it may be known as,
  // such as legacy names from prior versions
  String[] getAliases();

  // Convert the specified value into the type of values handled by this property
  T valueOf(String value);

  // Convert the specified value to a string
  String toString(T value);

  // Return the class object for the type of values of this property
  Class<T> valueType();

  // Return a concise localized description of the property
  String getDocumentation();
}

The class JPPFProperties holds a static enumeration of the predefined properties, each with a specific type parameter. For instance, the property whose name is "jppf.server.port" holds an int value and is obtained like this:

JPPFProperty<Integer> prop = JPPFProperties.SERVER_PORT;
System.out.printf("name: %s, default: %s, type: %s%n",
  prop.getName(), prop.getDefaultValue(), prop.valueType().getName());

As much as possible, the names of the constants in JPPFProperties are kept similar to the actual properties names: the constant names are all in upper case characters, the "jppf" prefix is removed, and the dots are replaced with underscores. For example "jppf.local.execution.enabled" will correspond to the LOCAL_EXECUTION_ENABLED constant.

The class TypedProperties has specific methods that use predefined properties:

public class TypedProperties extends Properties {
  // Get the value of a predefined property
  public <T> T get(JPPFProperty<T> property);

  // Set the value of a predefined property
  public <T> TypedProperties set(JPPFProperty<T> property, T value);

  // Remove the specified predefined property
  public <T> T remove(JPPFProperty<T> property);
}

Example usage:

int nbThreads = JPPFConfiguration.getProperties().get(JPPFProperties.PROCESSING_THREADS);
JPPFConfiguration.getProperties().set(JPPFProperties.DISCOVERY_ENABLED, true)
  .set(JPPFProperties.POOL_SIZE, 5).setString("custom.property", "some value");

Note the automatic type inference that is automatically performed by the compiler, as well as the preservation of the fluent interface for setting properties, allowing both custom and predefined properties to be set in the same statement.

JPPFConfiguration also has shortcut methods that make use of predefined properties:

public class JPPFConfiguration {
  // Get the value of a predefined property
  public static <T> T get(JPPFProperty<T> property);

  // Set the value of a predefined property
  public static <T> TypedProperties set(JPPFProperty<T> property, T value);

  // Remove the specified predefined property
  public static <T> T remove(JPPFProperty<T> property);
}

These methods resolve into equivalent calls to JPPFConfiguration.getProperties.get/set/remove(...).

For example, these two statements do exactly the same thing:

JPPFConfiguration.getProperties().set(JPPFProperties.SERVER_PORT, 11111);
JPPFConfiguration.set(JPPFProperties.SERVER_PORT, 11111);

Similarly for getting values:

int port;
port = JPPFConfiguration.getProperties().get(JPPFProperties.SERVER_PORT);
port = JPPFConfiguration.get(JPPFProperties.SERVER_PORT);

Combined with an import static statement, this leads to significantly smaller and more readable code:

import static org.jppf.utils.configuration.JPPFProperties.*;

...

int nbThreads = JPPFConfiguration.get(PROCESSING_THREADS);
JPPFConfiguration.set(DISCOVERY_ENABLED, true).set(POOL_SIZE, 5)
  .setString("custom.property", "some value").set(SERVER_PORT, 11111);