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 * a ContentResolver is a Helper for read/write byte[] content for a given key.
21 *
22 * <pre>
23 * Example configuration in settings4j.xml:
24 * --------------------------------------
25 * <contentResolver name="ClasspathContentResolver"
26 * class="org.settings4j.contentresolver.ClasspathContentResolver">
27 * </contentResolver>
28 * --------------------------------------
29 * </pre>
30 *
31 * This is usefull for {@link org.settings4j.connector.SystemPropertyConnector}
32 * or {@link org.settings4j.connector.PropertyFileConnector}.
33 * If you define a ContentResolver in this Connectors, you can rever to a File of the FileSystem or Classpath.
34 *
35 * <pre>
36 * Example Connector usage in settings4j.xml:
37 * --------------------------------------
38 * <connector name="SystemPropertyConnector" class="org.settings4j.connector.SystemPropertyConnector" >
39 * <contentResolver-ref ref="ClasspathContentResolver" />
40 * </connector>
41 * --------------------------------------
42 *
43 * Example usage in java-code:
44 *
45 * --------------------------------------
46 * // alternativ start myapp with -Dxyz=com/mycompany/myapp/xyz-config.xml
47 * System.setProperty("xyz", "com/mycompany/myapp/xyz-config.xml"); //refer to the ClasspathContentResolver
48 *
49 * // somewhere in myapp:
50 * byte[] xyzConfig = Settings4j.getContent("xyz"); // get Classpath-URL from the SystemPropertyConnector
51 * --------------------------------------
52 *
53 * </pre>
54 *
55 * @author Harald.Brabenetz
56 *
57 */
58 public interface ContentResolver {
59
60 /**
61 * Reads the Content for the given Key or null if nothing where found.
62 *
63 * @param key The key
64 * @return The byte[] Content or null if nothing where found.
65 */
66 byte[] getContent(String key);
67
68 /**
69 * Some Implementations of a {@link ContentResolver} are delegating the functionality
70 * to other ContentResolvers.<br />
71 * Examples are: {@link org.settings4j.contentresolver.UnionContentResolver}
72 *
73 * <pre>
74 * --------------------------------------
75 * <contentResolver name="DefaultContentResolver" class="org.settings4j.contentresolver.UnionContentResolver">
76 * <contentResolver-ref ref="FSContentResolver" />
77 * <contentResolver-ref ref="ClasspathContentResolver" />
78 * </contentResolver>
79 * --------------------------------------
80 * </pre>
81 *
82 * @param contentResolver the original contentResolver to delegate.
83 */
84 void addContentResolver(ContentResolver contentResolver);
85 }