Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SMILA/Project Concepts/Simple configuration handler"

Line 1: Line 1:
−
== 1 Description ==
+
== Description ==
  
 +
Many of the SMILA bundles require configuration files. The <tt>org.eclipse.smila.utils.config.ConfigUtils</tt> support developers in accessing the configuration files.
  
−
Many of bundles requires now configuration handling but its still in the discussion process. Its suggested to use now simple config loader instead of manual loading. It will be easier in the future replace it in normal config manager.
+
By default the bundle's configuration files reside in a folder with the same name as the full qualified bundle name in a <tt>configuration</tt> folder.
  
−
== 2 Discussion ==
+
For example the Jobmanager (bundle name is <tt>org.eclipse.smila.jobmanager</tt>) configuration resides in <tt>configuration/org.eclipse.smila.jobmanager</tt> and consists of several json files the Jobmanager accesses through the ConfigUtils.
  
 +
== Usage ==
 +
To use the <tt>ConfigUtils</tt> you have to import the package <tt>org.eclipse.smila.utils.config</tt>.
  
−
== 3 Technical Proposal ==
+
The ConfigUtils class provides several convenience methods to list or access files or streams in the bundle's configuration folder. This folder can be
 +
* a central config folder
 +
* a default config delivered and deployed with the bundle (only for streams and properties, see below)
 +
I.e. if a configuration file is requested, the central configuration folder is searched first, if there is no such file, the bundle will be examined for a fallback file and then this fallback file will be loaded, if it exists. If the requested file could not be determined or accessed, a <tt>ConfigurationLoadException</tt> will be thrown.
  
−
== 3.1 Usage ==
+
=== Configuring the configuration folder ===
 +
The central configuration folder will be determined in the following order:
 +
* a system property of the name <tt>org.eclipse.smila.utils.config.root</tt>
 +
* an environment variable of the name <tt>org.eclipse.smila.utils.config.root</tt>
 +
* <tt><org.eclipse.core.runtime.Platform.getInstallLocation()>/configuration</tt> (which will always yield a folder)
  
−
import package "org.eclipse.smila.utils.config" in Manifest.mf and use helper ConfigUtils
+
=== JavaDoc ===
 +
The ConfigUtils' JavaDoc can be found [http://build.eclipse.org/rt/smila/javadoc/current/org/eclipse/smila/utils/config/ConfigUtils.html here].
  
−
<source lang="Java">
+
=== Which methods have a bundle fallback and which not ===
−
public static InputStream getConfigStream(final String bundleName, final String configPath,
+
Not all methods really look up the entries in the bundle, because e.g. files cannot be loaded from the bundle, only streams can.
−
    final String defaultConfigPath);
+
*Lookup in the application's configuration folder only:
−
</source>
+
** getConfigFile
 +
** getConfigFilePath
 +
*Lookup all entries from the application's configuration folder if present or (only if no such folder has been found) list fallbacks from the bundle:
 +
** getConfigEntries
 +
*First look up in the application's configuration folder, if no such file exists, look up fallback in the bundle
 +
** getConfigStream
 +
** getConfigProperties
 +
** getConfigContent
  
−
There is also sortcut method
+
 
 +
== Example ==
  
 
<source lang="Java">
 
<source lang="Java">
−
public static InputStream getConfigStream(final String bundleName, final String configPath) {
+
public static final String BUNDLE_ID = "org.eclipse.smila.jobmanager";
−
    return getConfigStream(bundleName, configPath, configPath);
+
−
}
+
−
</source>
+
  
 +
...
  
−
== 3.2 How it works ==
+
    final InputStream bucketsJson =
 +
        ConfigUtils.getConfigStream(BUNDLE_ID, "buckets.json");
 +
      try {
 +
        final AnyMap bucketsAny = (AnyMap) _anyReader.readJsonStream(bucketsJson);
  
−
# Helper check system variable "org.eclipse.smila.utils.config.root" and, if its configured, tracts it as the configurations root folder.
+
        ...
−
# If not configurations folder is default: "{eclipse-path}/configuration"
+
−
# Its checks is configurations folder contains subfolder for bundle (bundleName) and file (configPath).
+
−
# If file is not found it loads default configuration (defaultConfigPath) directly from the bundle.
+
−
# If default resource not found - runtime error ConfigurationLoadException thrown
+
  
 +
      } finally {
 +
        IOUtils.closeQuietly(bucketsJson);
 +
      }
 +
</source>
 +
This snippet will load a file "buckets.json" from either the applications configuration folder <tt>config/org.eclipse.smila.jobmanager/buckets.json</tt> or if that did not exist from the same path within the bundle and converts it into an <tt>AnyMap</tt>.
  
 +
<source lang="java">
 +
public static final String BUNDLE_ID = "org.eclipse.smila.importing.state.objectstore";
  
−
== 3.3 Samples ==
+
...
−
 
+
−
<source lang="Java">
+
−
private static final String BUNDLE_ID = "org.eclipse.smila.connectivity.queue";
+
−
private static final String CONFIG_JMS_NAME = "jms.properties";
+
−
.............................................................................................
+
  
−
     InputStream inputStream = ConfigUtils.getConfigStream(BUNDLE_ID, CONFIG_JMS_NAME);
+
     Properties props;
−
    final Properties properties = new Properties();
+
 
     try {
 
     try {
−
       properties.load(inputStream);
+
       props = ConfigUtils.getConfigProperties(BUNDLE_ID, "deltastore.properties");
−
     } finally {
+
     } catch (final Exception ex) {
−
       IOUtils.closeQuietly(inputStream);
+
       _log.info("No configuration " + BUNDLE_ID + "/" + " found, using default settings.");
 +
      props = new Properties();
 
     }
 
     }
 
</source>
 
</source>
 +
This snippet loads properties from either the applications configuration folder <tt>configuration/org.eclipse.smila.importing.state.objectstore</tt> or the same path within the bundle itself.

Revision as of 11:33, 23 January 2012

Description

Many of the SMILA bundles require configuration files. The org.eclipse.smila.utils.config.ConfigUtils support developers in accessing the configuration files.

By default the bundle's configuration files reside in a folder with the same name as the full qualified bundle name in a configuration folder.

For example the Jobmanager (bundle name is org.eclipse.smila.jobmanager) configuration resides in configuration/org.eclipse.smila.jobmanager and consists of several json files the Jobmanager accesses through the ConfigUtils.

Usage

To use the ConfigUtils you have to import the package org.eclipse.smila.utils.config.

The ConfigUtils class provides several convenience methods to list or access files or streams in the bundle's configuration folder. This folder can be

  • a central config folder
  • a default config delivered and deployed with the bundle (only for streams and properties, see below)

I.e. if a configuration file is requested, the central configuration folder is searched first, if there is no such file, the bundle will be examined for a fallback file and then this fallback file will be loaded, if it exists. If the requested file could not be determined or accessed, a ConfigurationLoadException will be thrown.

Configuring the configuration folder

The central configuration folder will be determined in the following order:

  • a system property of the name org.eclipse.smila.utils.config.root
  • an environment variable of the name org.eclipse.smila.utils.config.root
  • <org.eclipse.core.runtime.Platform.getInstallLocation()>/configuration (which will always yield a folder)

JavaDoc

The ConfigUtils' JavaDoc can be found here.

Which methods have a bundle fallback and which not

Not all methods really look up the entries in the bundle, because e.g. files cannot be loaded from the bundle, only streams can.

  • Lookup in the application's configuration folder only:
    • getConfigFile
    • getConfigFilePath
  • Lookup all entries from the application's configuration folder if present or (only if no such folder has been found) list fallbacks from the bundle:
    • getConfigEntries
  • First look up in the application's configuration folder, if no such file exists, look up fallback in the bundle
    • getConfigStream
    • getConfigProperties
    • getConfigContent


Example

public static final String BUNDLE_ID = "org.eclipse.smila.jobmanager";
 
...
 
    final InputStream bucketsJson =
        ConfigUtils.getConfigStream(BUNDLE_ID, "buckets.json");
      try {
        final AnyMap bucketsAny = (AnyMap) _anyReader.readJsonStream(bucketsJson);
 
        ...
 
      } finally {
        IOUtils.closeQuietly(bucketsJson);
      }

This snippet will load a file "buckets.json" from either the applications configuration folder config/org.eclipse.smila.jobmanager/buckets.json or if that did not exist from the same path within the bundle and converts it into an AnyMap. 

public static final String BUNDLE_ID = "org.eclipse.smila.importing.state.objectstore";
 
...
 
    Properties props;
    try {
      props = ConfigUtils.getConfigProperties(BUNDLE_ID, "deltastore.properties");
    } catch (final Exception ex) {
      _log.info("No configuration " + BUNDLE_ID + "/" + " found, using default settings.");
      props = new Properties();
    }

This snippet loads properties from either the applications configuration folder configuration/org.eclipse.smila.importing.state.objectstore or the same path within the bundle itself.

Retrieved from "https://wiki.eclipse.org/index.php?title=SMILA/Project_Concepts/Simple_configuration_handler&oldid=285823"

Back to the top