1 /* ***************************************************************************
2 * Copyright (c) 2008 Brabenetz Harald, Austria.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *
16 *****************************************************************************/
17 package org.settings4j;
18
19 /**
20 * An implementation of this Interface can return Values for a given key.<br />
21 * Not every implementation can write a value for a given key
22 * (e.g.: {@link org.settings4j.connector.ClasspathConnector} )<br />
23 * String, byte[] (content) and Objects should be possible.<br />
24 * <br />
25 * A Connector can use the Helper Implementations
26 * {@link ContentResolver} and {@link ObjectResolver} for internal use.<br />
27 * Not ervery Connector needs them, Read the Javadoc of the concrete implementaiton.<br />
28 *
29 * <pre>
30 *
31 * Example configuration in settings4j.xml:
32 * --------------------------------------
33 * <connector name="ClasspathConnector" class="org.settings4j.connector.ClasspathConnector" >
34 * <objectResolver-ref ref="DefaultObjectResolver" />
35 * </connector>
36 * --------------------------------------
37 *
38 * </pre>
39 * @author Harald.Brabenetz
40 *
41 */
42 public interface Connector {
43
44 /**
45 * return a String-Value for the given key.
46 *
47 * @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
48 * @return the String-Value for the given key
49 */
50 String getString(String key);
51
52 /**
53 * return a byte[]-Value for the given key.
54 * <p>
55 * The concrete implementation can use the ContentResolver if required
56 *
57 * @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
58 * @return the byte[]-Value for the given key
59 */
60 byte[] getContent(String key);
61
62 /**
63 * return a Object-Value for the given key.
64 * <p>
65 * The concrete implementation can use the ObjectResolver if required<br />
66 *
67 * @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
68 * @return the Object-Value for the given key, or null if no value where found.
69 */
70 Object getObject(String key);
71
72 /**
73 * set a ContentResolver as Helper for {@link #getContent(String)}.
74 *
75 * @param contentResolver the ContentResolver to set.
76 */
77 void setContentResolver(ContentResolver contentResolver);
78
79 /**
80 * set a ObjectResolver as Helper for {@link #getObject(String)}.
81 *
82 * @param objectResolver the ObjectResolver to set.
83 */
84 void setObjectResolver(ObjectResolver objectResolver);
85
86 /**
87 * Add a Connector if you needed inside the {@link #init()} Methode.<br/>
88 * Or you can use this connectors inside the settings4j.xml to set a parameter/property
89 *
90 * <pre>
91 *
92 * Example configuration in settings4j.xml:
93 * --------------------------------------
94 * <connector name="PropertyFileConnector" class="org.settings4j.connector.PropertyFileConnector">
95 * <param name="propertyFromContent"
96 * value="<b>${connectors.content['org/settings4j/config/propertyFile.properties']}</b>" />
97 * <contentResolver-ref ref="DefaultContentResolver" />
98 * <b><connector-ref ref="ClasspathConnector" /></b>
99 * </connector>
100 * --------------------------------------
101 *
102 * </pre>
103 * @param connector the Connector to set.
104 */
105 void addConnector(Connector connector);
106
107 /**
108 * Will be called after all properties have been set.
109 * This function will only called one times.
110 *
111 */
112 void init();
113
114 /**
115 * Return The name Of this Connector. The Name is required
116 * in all {@link Settings4j}.set*(..., String connectorName) Methods.
117 *
118 * @return The name Of this Connector.
119 */
120 String getName();
121
122 /**
123 * Set the name of the Connector defined in the settings4j.xml configuration:
124 * <pre>
125 * --------------------------------------
126 * <connector <b>name="PropertyFileConnector"</b> ....>
127 * ....
128 * </connector>
129 * --------------------------------------
130 * </pre>
131 *
132 * @param name the Name of this Connector.
133 */
134 void setName(String name);
135
136 }