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