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