org.settings4j.Settings4jInstance Maven / Gradle / Ivy
/* ***************************************************************************
* Copyright (c) 2008 Brabenetz Harald, Austria.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*****************************************************************************/
package org.settings4j;
import java.util.List;
import java.util.Map;
/**
* SettingsInstance is used to get simply access to Application settings.
*
* @see Settings4j
* @author Harald.Brabenetz
*/
public interface Settings4jInstance {
/**
* return the found String-Value for the given key.
* The {@link Settings4jInstance} Instance iterates all his {@link Connector}s and return the first found Value.
*
* Returns null if no connector found a Value for the given key
*
* @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
* @return the found String-Value for the given key
*/
String getString(String key);
/**
* return the found byte[]-Value for the given key.
* The {@link Settings4jInstance} Instance iterates all his {@link Connector}s and return the first found Value.
*
* Returns null if no connector found a Value for the given key
*
* @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
* @return the found byte[]-Value for the given key
*/
byte[] getContent(String key);
/**
* return the found Object-Value for the given key.
* The {@link Settings4jInstance} iterates all his {@link Connector}s and return the first found Value.
* Returns null if no connector found a Value for the given key
*
* @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
* @return the found Object-Value for the given key
*/
Object getObject(String key);
/**
* Add a {@link Connector}.
* This method will be call, if you create a connector-ref to a connector configuration in your settings4j.xml
*
*
* Example configuration in settings4j.xml:
* --------------------------------------
* <settings name="com.mycompany" >
* <connector-ref name="DBConnector" />
* </settings>
* --------------------------------------
*
*
* @param connector The connector to add.
*/
void addConnector(Connector connector);
/**
* Add a custom {@link Connector} to the right position in relation to the other connectors.
* This method can be used to add custom connectors into the {@link Settings4jInstance}
*
*
Example usage 1:
*
*
* --------------------------------------
* Connector myConnector = ...
* addConnector(myConnector, {@link ConnectorPositions}.afterLast(SystemPropertyConnector.class));
* --------------------------------------
*
*
* Example usage 2:
* {@link ConnectorPositions}.afterLast(SystemPropertyConnector.class) will throw an exception if the
* {@link Settings4jInstance} doesn't have a SystemPropertyConnector.
* To prevent an Exception you can provide multiple ConnectorPositions as fallback:
*
*
* --------------------------------------
* Connector myConnector = ...
* addConnector(myConnector, ConnectorPositions.firstValid(//
* ConnectorPositions.afterLast(SystemPropertyConnector.class),
* ConnectorPositions.atFirst() // fallback if no SystemPropertyConnector exists.
* )
* );
* --------------------------------------
*
*
* Example usage 3:
* {@link #addConnector(Connector)} will throw an exception if a connector with the same name already exists.
* To prevent this Exception you should also check with {@link #getConnector(String)} if the Connector already
* exists:
*
*
* --------------------------------------
* Connector myConnector = ...
* if(getConnector(myConnector.getName()) == null) {
* addConnector(myConnector, ConnectorPositions.firstValid(//
* ConnectorPositions.afterLast(SystemPropertyConnector.class),
* ConnectorPositions.atFirst() // fallback if no SystemPropertyConnector exists.
* )
* );
* }
* --------------------------------------
*
*
* @param connector The connector to add.
* @param position The position where the connector should be added.
*/
void addConnector(Connector connector, ConnectorPosition position);
/**
* Remove all Settings. (Internal use only)
*/
void removeAllConnectors();
/**
* The key mapping defined in settings4j.xml.
*
* if some Sub-Modules of your App defines separated Keys for e.g. the DataSource, you can refer it to one unique
* Key:
*
*
* Example:
* <mapping name="defaultMapping">
* <entry key="com/mycompany/moduleX/datasource" ref-key="global/datasource"/>
* <entry key="com/mycompany/moduleY/datasource" ref-key="global/datasource"/>
* </mapping>
*
*
* Settings4j.getXXX("com/mycompany/moduleX/datasource");
* should return the configured value under "global/datasource"
*
*
* @return the Mappings of this Settings-Object (without inheritances)
*/
Map getMapping();
/**
* Set the mapping for this Settings-Object without inheritance.
* This method will be call, if you create a mapping-ref to a mapping configuration in your settings4j.xml
*
*
* Example:
* <root mapping-ref="defaultMapping" >
* ...
* </root>
*
* <mapping name="defaultMapping">
* <entry key="com/mycompany/moduleX/datasource" ref-key="global/datasource"/>
* <entry key="com/mycompany/moduleY/datasource" ref-key="global/datasource"/>
* </mapping>
*
*
* @param mapping The Mapping between available settings to used settings.
*/
void setMapping(Map mapping);
/**
* Return a List off {@link Connector} who can be used with this {@link Settings4jInstance} instance.
*
* @return a list off all Connectors who can be used with this {@link Settings4jInstance} instance
*/
List getConnectors();
/**
* Return the {@link Connector} for the given Name.
*
* @param connectorName The Connector Name.
* @return The {@link Connector} for the given Name.
*/
Connector getConnector(String connectorName);
}