Hydra

• Home
• Screenshots
• License
• News

Documentation

• Tutorials
• Javadoc Pages

Download

• Distributions

Project Management

• Contributers

Understanding Hydra 2.0: The Hydra API

Content

• Creating the Hydra configuration
• Accessing the Hydra configuration
• Writing and reading the Hydra configuration
• Settings of Hydra elements

Creating the Hydra configuration

The ConfigRoot is the root of the Hydra tree and is used to access the configuration. It is created by calling the appropriate method from the class HydraFactory.

//Hydra uses log4j. When the ConfigRoot is created, 
//you can decide whether to enable log4j messages generated by Hydra.
//Passing true will configure log4j to print logging messages to the console.
//Passing false will not configure log4j, instead you can configure log4j to your own needs.

ConfigRoot root = HydraFactory.createConfigRoot(true);

Having an empty ConfigRoot, we can go adding some ConfigKeys to it. ConfigKeys are added by calling the addConfigKey(String label) method from the parent node. If no Exception is thrown, the newly added ConfigKey is returned by this method.

try {
	ConfigKey test = root.addConfigKey("test"); //throws IllegalLabelException
	test.setActive(true); //throws IllegalSelectionException
	root.getKeySelectionMode().setOneMode(); //throws IllegalSelectionException
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSelectionException e) {
	e.printStackTrace();
}

The IllegalLabelException might be thrown, if another ConfigKey with the same label already exists at the parent node. The IllegalSelectionException might be thrown, if setting the active status of child ConfigKeys or changing the key selection mode of the parent node does not comply with the current selection.

In our example we choose the 1 key selection mode, after setting exactly one element active, so no Exception will be thrown.

Next, we will add some ConfigValues to the new ConfigKey, change the value permission to MODIFY, select one ConfigValue and set the value selection mode to 1.

try {
	ConfigValue v1 = test.addValue("v1"); //throws IllegalLabelException
	ConfigValue v2 = test.addValue("v2"); //throws IllegalLabelException
	ConfigValue v3 = test.addValue("v3"); //throws IllegalLabelException
	test.setValuePermission(ConfigValue.PERMISSION_MODIFY); //throws IllegalSettingsException
	v1.setActive(true); //throws IllegalSelectionException
	test.getValueSelectionMode().setOneMode(); //throws IllegalSelectionException
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSettingsException e) {
	e.printStackTrace();
} catch (IllegalSelectionException e) {
	e.printStackTrace();
}

Changing the value permission is done by passing the new value permission String to the setValuePermission(String s) method of the ConfigKey. This method throws an IllegalSettingsException if the String is illegal, but since we are using the right constant from class ConfigValue, no Exception is thrown here.

To finish up the creation of our Hydra configuration, we will add two more ConfigKeys to the "test" ConfigKey and set the first one to be active.

try {
	ConfigKey a = test.addConfigKey("a"); //throws IllegalLabelException
	ConfigKey b = test.addConfigKey("b"); //throws IllegalLabelException
	a.setActive(true); //throws IllegalSelectionException
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSelectionException e) {
	e.printStackTrace();
}

The resulting Hydra configuration looks like this:

Removing elements is achieved by calling the removeConfigKey(ConfigKey c) and removeValue(ConfigValue v) methods from the appropriate elements.

Accessing the Hydra configuration

Having created a Hydra configuration, we most likely want to use it in Java applications by reading the selected elements. The class HydraAPI offers some convenience methods for this purpose. In our example configuration, we might want to know which ConfigKeys and ConfigValues from the "test" ConfigKey are active. You can use the following code:

String p = test.getHydraPath();
try {
	System.out.println(HydraAPI.getActiveKey(root,p));
	System.out.println(HydraAPI.getActiveValue(root,p));
} catch (IllegalPathException e) {
	e.printStackTrace();
} catch (NoActiveKeyAvailableException e) {
	e.printStackTrace();
} catch (NoActiveValueAvailableException e) {
	e.printStackTrace();
}

The methods from the class HydraAPI simply require the ConfigRoot and the path to the ConfigKey, which shall be read out. The path is a slash-separated concatenation of the labels of the nodes, which lead to the desired ConfigKey. Here the path would be "/test". The output of the above code is:

a
v1

Writing and reading the Hydra configuration

After creating the Hydra configuration, you might want to store it. The Hydra configuration is stored in XML format. To write the XML data, you can use the write(OutputStream out, boolean close) method from the ConfigRoot.

try {
	FileOutputStream out = new FileOutputStream("examples/api.hydra");
	root.write(out,true);
} catch (FileNotFoundException e) {
	e.printStackTrace();
} catch (IOException e) {
	e.printStackTrace();
}

If you want to read an existing Hydra configuration, you can use the createConfigRoot(boolean log, InputStream in) from the class HydraFactory. The boolean value determines whether log4j should be enabled.

try {
	FileInputStream in = new FileInputStream("examples/api.hydra");
	ConfigRoot read = HydraFactory.createConfigRoot(true,in);
} catch (FileNotFoundException e) {
	e.printStackTrace();
} catch (XMLException e) {
	e.printStackTrace();
} catch (IllegalLabelException e) {
	e.printStackTrace();
} catch (IllegalSelectionException e) {
	e.printStackTrace();
} catch (IllegalSettingsException e) {
	e.printStackTrace();
}

The various Exceptions are thrown, if the XML data to read from has errors, which would result in a corrupted Hydra configuration.

Settings of Hydra elements

When Hydra elements are created via the API, they are initialzed with their default settings. Here is an overview of the most important settings and the methods to alter them. For more detailed information about the methods consult the Javadoc Pages.

The ConfigRoot

The ConfigKey

The ConfigValue