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  
24  import org.settings4j.settings.SettingsManager;
25  
26  
27  /**
28   * Settings is used to get simply access to Application settings.
29   *
30   * <pre>
31   * Example usage java:
32   * --------------------------------------
33   * public class SettingsManager {
34   *     public static String getMyFormula() {
35   *         return Settings4j.getString("com/mycompany/mycalculation/my-formula");
36   *     }
37   * }
38   * --------------------------------------
39   *
40   * </pre>
41   *
42   * @author Harald.Brabenetz
43   */
44  public final class Settings4j {
45  
46      /** Hide Constructor (Utility-Pattern). */
47      private Settings4j() {
48          super();
49      }
50  
51      /**
52       * return the found String-Value for the given key.<br>
53       * The {@link Settings4j} Instance iterates all his {@link Connector} and return the first found Value.<br>
54       * <br>
55       * Returns null if no connector found a Value for the given key<br>
56       * <p>
57       * If no custom settings4j.xml exist in classpath, the following default order will be used:
58       * </p>
59       * <ol>
60       * <li>check if value for {@link System#getProperty(String)} exist (see {@link org.settings4j.connector.SystemPropertyConnector} ),</li>
61       * <li>else check if value for {@link javax.naming.InitialContext#lookup(String)} exist (see {@link org.settings4j.connector.JNDIConnector} ),</li>
62       * <li>else check if in {@link java.util.prefs.Preferences#userRoot()} and {@link java.util.prefs.Preferences#systemRoot()} the Value for
63       * {@link java.util.prefs.Preferences#get(String, String)} exist (see {@link org.settings4j.connector.PreferencesConnector} ),</li>
64       * <li>else check if the value exist in Classpath (see {@link org.settings4j.connector.ClasspathConnector} ).</li>
65       * </ol>
66       *
67       * @param key
68       *        the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
69       * @return the found String-Value for the given key
70       */
71      public static String getString(final String key) {
72          return getSettings().getString(key);
73      }
74  
75      /**
76       * return the found byte[]-Value for the given key.
77       * <p>
78       * { getSettings().getAllConnectors(); } The {@link Settings4j} Instance iterates all his {@link Connector} and return the first found Value.
79       * </p>
80       * <p>
81       * Returns null if no connector found a Value for the given key<br>
82       * </p>
83       * <p>
84       * If no custom settings4j.xml exist in classpath, the behavior is like {@link #getString(String)}, but only the
85       * {@link org.settings4j.connector.ClasspathConnector} can return a byte[] content directly.<br>
86       * The other Connectors calls there getString(...) Method to get a valid Filesystempath or Classpath.
87       * </p>
88       * <p>
89       * e.g {@link org.settings4j.connector.SystemPropertyConnector}:<br>
90       * Start the Application with -Dcom/mycompany/myapp/myParameterKey=file:D:/PathToMyFileContent<br>
91       * Then: <code>getContent("com/mycompany/myapp/myParameterKey")</code> will return the byte[] Content of <code>"file:D:/PathToMyFileContent"</code>.
92       * </p>
93       * <p>
94       * Valid Path-Prefixes are "file:" and "classpath:".<br>
95       * See {@link ContentResolver} and {@link org.settings4j.contentresolver.FSContentResolver} and
96       * {@link org.settings4j.contentresolver.ClasspathContentResolver}.
97       * </p>
98       *
99       * @param key
100      *        the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
101      * @return the found byte[]-Value for the given key
102      */
103     public static byte[] getContent(final String key) {
104         return getSettings().getContent(key);
105     }
106 
107     /**
108      * return the found Object-Value for the given key.<br>
109      * The {@link Settings4j} Instance iterates all his {@link Connector} and return the first found Value.<br>
110      * <p>
111      * Returns null if no connector found a Value for the given key<br>
112      * </p>
113      * <p>
114      * If no custom settings4j.xml exist in classpath, the behavior is like {@link #getString(String)}, but only the
115      * {@link org.settings4j.connector.JNDIConnector} can return an Object directly.<br>
116      * The other Connectors calls there getContent(...) Method to get a content which can be transformed to an Object.<br>
117      * See {@link ObjectResolver}.
118      * </p>
119      *
120      * @param key
121      *        the Key for the configuration-property. e.g.: "com/mycompany/myapp/myParameterKey"
122      * @return the found Object-Value for the given key
123      */
124     public static Object getObject(final String key) {
125         return getSettings().getObject(key);
126     }
127 
128     /**
129      * Get the {@link Settings4jRepository} where this Settings-Object is stored.
130      *
131      * @return the {@link Settings4jRepository} where this Settings-Object is stored.
132      */
133     public static Settings4jRepository getSettingsRepository() {
134         return SettingsManager.getSettingsRepository();
135     }
136 
137     /**
138      * Delegate to {@link SettingsManager#getRootSettings()}.
139      *
140      * @see SettingsManager#getRootSettings()
141      */
142     private static Settings4jInstance getSettings() {
143         return SettingsManager.getSettings();
144     }
145 
146     /**
147      * Return a List off {@link Connector} who can be used with this {@link Settings4j} instance.
148      *
149      * @return a list off all Connectors who can be used with this {@link Settings4j} instance
150      */
151     public static List<Connector> getConnectors() {
152         return getSettings().getConnectors();
153     }
154 
155     /**
156      * Return the {@link Connector} for the given Name.
157      *
158      * @param connectorName The Connector Name.
159      * @return The {@link Connector} for the given Name.
160      */
161     public static Connector getConnector(final String connectorName) {
162         return getSettings().getConnector(connectorName);
163     }
164 }