View Javadoc
1   /*
2    * #%L
3    * settings4j
4    * ===============================================================
5    * Copyright (C) 2008 - 2015 Brabenetz Harald, Austria
6    * ===============================================================
7    * Licensed under the Apache License, Version 2.0 (the "License");
8    * you may not use this file except in compliance with the License.
9    * You may obtain a copy of the License at
10   * 
11   *      http://www.apache.org/licenses/LICENSE-2.0
12   * 
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License.
18   * #L%
19   */
20  package org.settings4j;
21  
22  import java.util.List;
23  import java.util.Map;
24  
25  
26  /**
27   * SettingsInstance is used to get simply access to Application settings.
28   *
29   * @see Settings4j
30   * @author Harald.Brabenetz
31   */
32  public interface Settings4jInstance {
33  
34      /**
35       * return the found String-Value for the given key.<br>
36       * The {@link Settings4jInstance} Instance iterates all his {@link Connector}s and return the first found Value.
37       * <p>
38       * Returns null if no connector found a Value for the given key
39       * </p>
40       *
41       * @param key
42       *        the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
43       * @return the found String-Value for the given key
44       */
45      String getString(String key);
46  
47      /**
48       * return the found byte[]-Value for the given key.<br>
49       * The {@link Settings4jInstance} Instance iterates all his {@link Connector}s and return the first found Value.
50       * <p>
51       * Returns null if no connector found a Value for the given key
52       * </p>
53       *
54       * @param key
55       *        the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
56       * @return the found byte[]-Value for the given key
57       */
58      byte[] getContent(String key);
59  
60      /**
61       * return the found Object-Value for the given key.<br>
62       * The {@link Settings4jInstance} iterates all his {@link Connector}s and return the first found Value. <br>
63       * Returns null if no connector found a Value for the given key<br>
64       *
65       * @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
66       * @return the found Object-Value for the given key
67       */
68      Object getObject(String key);
69  
70      /**
71       * Add a {@link Connector}.
72       * <p>
73       * This method will be call, if you create a connector-ref to a connector configuration in your settings4j.xml
74       * </p>
75       *
76       * <pre>
77       * Example configuration in settings4j.xml:
78       * --------------------------------------
79       * &lt;settings name="com.mycompany" &gt;
80       *     &lt;connector-ref name="DBConnector" /&gt;
81       * &lt;/settings&gt;
82       * --------------------------------------
83       * </pre>
84       *
85       * @param connector
86       *        The connector to add.
87       */
88      void addConnector(Connector connector);
89  
90      /**
91       * Add a custom {@link Connector} to the right position in relation to the other connectors.
92       * <p>
93       * This method can be used to add custom connectors into the {@link Settings4jInstance}
94       * </p>
95       * <h3>Example usage 1:</h3>
96       *
97       * <pre>
98       * --------------------------------------
99       * Connector myConnector = ...
100      * addConnector(myConnector, {@link ConnectorPositions}.afterLast(SystemPropertyConnector.class));
101      * --------------------------------------
102      * </pre>
103      *
104      * <h3>Example usage 2:</h3>
105      * <p>
106      * <code>{@link ConnectorPositions}.afterLast(SystemPropertyConnector.class)</code> will throw an exception if the {@link Settings4jInstance} doesn't have a
107      * SystemPropertyConnector. <br>
108      * To prevent an Exception you can provide multiple ConnectorPositions as fallback:
109      * </p>
110      *
111      * <pre>
112      * --------------------------------------
113      * Connector myConnector = ...
114      * addConnector(myConnector, ConnectorPositions.firstValid(//
115      *     ConnectorPositions.afterLast(SystemPropertyConnector.class),
116      *     ConnectorPositions.atFirst() // fallback if no SystemPropertyConnector exists.
117      *   )
118      * );
119      * --------------------------------------
120      * </pre>
121      *
122      * <h3>Example usage 3:</h3>
123      * <p>
124      * {@link #addConnector(Connector)} will throw an exception if a connector with the same name already exists. <br>
125      * To prevent this Exception you should also check with {@link #getConnector(String)} if the Connector already exists:
126      * </p>
127      *
128      * <pre>
129      * --------------------------------------
130      * Connector myConnector = ...
131      * if(getConnector(myConnector.getName()) == null) {
132      *   addConnector(myConnector, ConnectorPositions.firstValid(//
133      *       ConnectorPositions.afterLast(SystemPropertyConnector.class),
134      *       ConnectorPositions.atFirst() // fallback if no SystemPropertyConnector exists.
135      *     )
136      *   );
137      * }
138      * --------------------------------------
139      * </pre>
140      *
141      * @param connector
142      *        The connector to add.
143      * @param position
144      *        The position where the connector should be added.
145      */
146     void addConnector(Connector connector, ConnectorPosition position);
147 
148     /**
149      * Remove all Settings. (Internal use only)
150      */
151     void removeAllConnectors();
152 
153     /**
154      * The key mapping defined in settings4j.xml.
155      * <p>
156      * if some Sub-Modules of your App defines separated Keys for e.g. the DataSource, you can refer it to one unique Key:
157      * </p>
158      *
159      * <pre>
160      * Example:
161      * &lt;mapping name="defaultMapping"&gt;
162      *     &lt;entry key="com/mycompany/moduleX/datasource" ref-key="global/datasource"/&gt;
163      *     &lt;entry key="com/mycompany/moduleY/datasource" ref-key="global/datasource"/&gt;
164      * &lt;/mapping&gt;
165      * </pre>
166      * <p>
167      * Settings4j.getXXX("com/mycompany/moduleX/datasource"); <br>
168      * should return the configured value under "global/datasource"
169      * </p>
170      *
171      * @return the Mappings of this Settings-Object (without inheritances)
172      */
173     Map<String, String> getMapping();
174 
175     /**
176      * Set the mapping for this Settings-Object without inheritance.
177      * <p>
178      * This method will be call, if you create a mapping-ref to a mapping configuration in your settings4j.xml
179      * </p>
180      *
181      * <pre>
182      * Example:
183      * &lt;root mapping-ref="<b>defaultMapping</b>" &gt;
184      *    ...
185      * &lt;/root&gt;
186      *
187      * &lt;mapping name="<b>defaultMapping</b>"&gt;
188      *     &lt;entry key="com/mycompany/moduleX/datasource" ref-key="global/datasource"/&gt;
189      *     &lt;entry key="com/mycompany/moduleY/datasource" ref-key="global/datasource"/&gt;
190      * &lt;/mapping&gt;
191      * </pre>
192      *
193      * @param mapping
194      *        The Mapping between available settings to used settings.
195      */
196     void setMapping(Map<String, String> mapping);
197 
198     /**
199      * Return a List off {@link Connector} who can be used with this {@link Settings4jInstance} instance.
200      *
201      * @return a list off all Connectors who can be used with this {@link Settings4jInstance} instance
202      */
203     List<Connector> getConnectors();
204 
205     /**
206      * Return the {@link Connector} for the given Name.
207      *
208      * @param connectorName The Connector Name.
209      * @return The {@link Connector} for the given Name.
210      */
211     Connector getConnector(String connectorName);
212 }