View Source

Summary

OSID Runtime manages configuration for OSID Providers.

Accessing Configuration

Typically, configuration is performed within the initialize() method of an OSID Provider. A ValueRetrievalSession available from the OsidRuntimeManager is used for looking up configuration values.

 public class MyCalendarManager
    implements org.osid.calendaring.CalendaringManager {
  
    private org.osid.logging.LoggingManager logger;
    private static final org.osid.id.Id LOGGING_IMPL_PARAMETER_ID = new net.okapia.primordium.id.BasicId("myCalendar", "configuration", "logging_osid");
 
 
    @OSID @Override
    public void initialize(org.osid.OsidRuntimeManager runtime)
        throws org.osid.ConfigurationErrorException,
               org.osid.OperationFailedException {
            
        try (org.osid.configuration.ValueRetrievalSession session =  runtime.getConfiguration()) {
            session.useComparativeView();
            session.useFederatedConfigurationView();
            org.osid.configuration.Value impl = session.getValueByParameter(LOGGING_IMPL_PARAMETER_ID);
     
            try {
                this.logger = (org.osid.logging.LoggingManager) runtime.getOsidManager(OSID.LOGGING, value.getStringValue(),
                                                                                       net.okapia.osid.kilimanjaro.Versions.LATEST.getVersion());
            } catch (org.osid.NotFoundException nfe) {
            throw new org.osid.ConfigurationErrorException("calendaring impl not found", nfe);
            }
        } catch (org.osid.PermissionDeniedException | org.osid.NotFoundException e) {
            throw new org.osid.ConfigurationErrorException(e);
        }

        return;
    }
 
    ....
}

Some things of note:

The OSID Runtime delivers an OsidSession of the Configuration OSID that defines operations for retrieving values.
All OsidSessions are Autocloseables and should be explicitly closed when no longer needed.
Views in OsidSessions should be explicitly set for desired behavior. OSIDs don't define defaults.
Configuration parameters are identified by Ids and may be hard coded or factored out into some constants file.
The exceptions don't line up between the OsidManager.initialize() and ValueRetrievalSession.getValueByParameter(). The twist in semantics requires a catch & rethrow.

Jamocha's AbstractOsidManager makes this a bit easier.

 public class MyCalendarManager
    extends net.okapia.osid.jamocha.calendaring.spi.AbstractCalendaringManager
    implements org.osid.calendaring.CalendaringManager {
  
    private org.osid.logging.LoggingManager logger;
    private static final org.osid.id.Id LOGGING_IMPL_PARAMETER_ID = new net.okapia.primordium.id.BasicId("myCalendar", "configuration", "logging_osid");
 
 
    @OSID @Override
    public void initialize(org.osid.OsidRuntimeManager runtime)
        throws org.osid.ConfigurationErrorException,
               org.osid.OperationFailedException {
            
        super.initialize(runtime);
        this.logger = (org.osid.logging.LoggingManager) loadOsidManager(OSID.LOGGING, 
                                                                        getConfigurationValue(LOGGING_IMPL_PARAMETER_ID).getStringValue());
          
        return;
    }
 
    ....
}

Single Vs. Multiple Values

There are two variants of value retrieval operations:

single value (shown in the example above)
multi-value

The Configuration OSID allows for a Parameter to have multiple Values. This makes sense if the Configuration OSID Consumer, the Calendaring OSID Provider in this case, is prepared to deal with multiple values. Our little example isn't. If there were multiple string values for that Parameter, one was simply selected for us by the Configuration OSID Provider. Multi-valued configurations are useful for federating and fallbacks.

Kilimanjaro's Configuration Files

Base Configuration

<?xml version="1.0" encoding="utf-8" standalone="no"?>

<configuration xmlns="urn:inet:osid.org:schemas:configuration"
               lastmod="2010-01-29T16:25:00Z">

    <displayName>Example Configuration</displayName>
    <description>
        <div>An eample configuration to demonstrate the Base Configuration
        OSID Provider. This implementation is not quite as flexible as
	    the Configuration OSID allows, but does handle parameter
	    metadata and multiple values.</div>
    </description>

    <parameter id="shouldThisWork" syntax="boolean">
    	<displayName>Wor</displayName>
	    <description>
            <div class="description">A parameter to specify whether or not this
            code should work. If set to false, <em>random bugs</em> may occur.</div> 
	    </description>
	    <value>
            <boolean>true</boolean>
	    </value>
    </parameter>

    <parameter id="favoriteNumber" syntax="cardinal">
	    <displayName>Favorite Number</displayName>
	    <description>
            Our favorite number between 1 and 10.
	    </description>
	    <value>
            <cardinal>3</cardinal>
	    </value>
    </parameter>

    <parameter id="birthdate" syntax="datetime">
	    <displayName>Birthday</displayName>
	    <description>
            A date on which someone was born specified in ISO format.
	    </description>
	    <value>
            <datetime>1979-08-20</datetime>
    	</value>
    </parameter>
 
    <parameter id="serverName" syntax="string">
        <displayName>Server Name</displayName>
        <description>
            The name of our database server that contains the projects
            plans for the product we wish we could build.
        </description>
        <value priority="1">
            <string>www1.company.com</string>
        </value>
        <value priority="1">
            <string>www2.company.com</string>
        </value>
        <value priority="10">
            <string>backup.company.com</string>
        </value>
    </parameter>
</configuration>

The above is an example of a base configuration file that defines Parameters and Values for the Configuration OSID.