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 /**
23 * An implementation of this Interface can return Values for a given key.<br>
24 * <p>
25 * Not every implementation can write a value for a given key (e.g.: {@link org.settings4j.connector.ClasspathConnector} )<br>
26 * String, byte[] (content) and Objects should be possible.<br>
27 * <br>
28 * A Connector can use the Helper Implementations {@link ContentResolver} and {@link ObjectResolver} for internal use.<br>
29 * Not ervery Connector needs them, Read the Javadoc of the concrete implementaiton.
30 * </p>
31 *
32 * <pre>
33 * Example configuration in settings4j.xml:
34 * --------------------------------------
35 * <connector name="ClasspathConnector" class="org.settings4j.connector.ClasspathConnector" >
36 * <objectResolver-ref ref="DefaultObjectResolver" />
37 * </connector>
38 * --------------------------------------
39 * </pre>
40 *
41 * @author Harald.Brabenetz
42 */
43 public interface Connector {
44
45 /**
46 * return a String-Value for the given key.
47 *
48 * @param key the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
49 * @return the String-Value for the given key
50 */
51 String getString(String key);
52
53 /**
54 * return a byte[]-Value for the given key or <code>null</code> if no file-content for the key where found.
55 * <p>
56 * The concrete implementation can use the ContentResolver if required
57 * </p>
58 *
59 * @param key
60 * the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
61 * @return the byte[]-Value for the given key
62 */
63 byte[] getContent(String key);
64
65 /**
66 * return a Object-Value for the given key.
67 * <p>
68 * The concrete implementation can use the ObjectResolver if required<br>
69 * </p>
70 *
71 * @param key
72 * the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
73 * @return the Object-Value for the given key, or null if no value where found.
74 */
75 Object getObject(String key);
76
77 /**
78 * set a ContentResolver as Helper for {@link #getContent(String)}.
79 *
80 * @param contentResolver the ContentResolver to set.
81 */
82 void setContentResolver(ContentResolver contentResolver);
83
84 /**
85 * set a ObjectResolver as Helper for {@link #getObject(String)}.
86 *
87 * @param objectResolver the ObjectResolver to set.
88 */
89 void setObjectResolver(ObjectResolver objectResolver);
90
91 /**
92 * Add a Connector if you needed inside the {@link #init()} Methode.
93 * <p>
94 * Or you can use this connectors inside the settings4j.xml to set a parameter/property
95 * </p>
96 *
97 * <pre>
98 *
99 * Example configuration in settings4j.xml:
100 * --------------------------------------
101 * <connector name="PropertyFileConnector" class="org.settings4j.connector.PropertyFileConnector">
102 * <param name="propertyFromContent"
103 * value="<b>${connectors.content['org/settings4j/config/propertyFile.properties']}</b>" />
104 * <contentResolver-ref ref="DefaultContentResolver" />
105 * <b><connector-ref ref="ClasspathConnector" /></b>
106 * </connector>
107 * --------------------------------------
108 * </pre>
109 *
110 * @param connector
111 * the Connector to set.
112 */
113 void addConnector(Connector connector);
114
115 /**
116 * Will be called after all properties have been set.
117 * This function will only called one times.
118 *
119 */
120 void init();
121
122 /**
123 * Return The name Of this Connector. The Name is required
124 * in all {@link Settings4j}.set*(..., String connectorName) Methods.
125 *
126 * @return The name Of this Connector.
127 */
128 String getName();
129
130 /**
131 * Set the name of the Connector defined in the settings4j.xml configuration:
132 * <pre>
133 * --------------------------------------
134 * <connector <b>name="PropertyFileConnector"</b> ....>
135 * ....
136 * </connector>
137 * --------------------------------------
138 * </pre>
139 *
140 * @param name the Name of this Connector.
141 */
142 void setName(String name);
143
144 }