1 package com.sourceforge.jpatterns.core.configuration;
2
3 import java.io.Serializable;
4 import java.util.Set;
5
6 /**
7 * This interface defines the methods would be used later for the working with the configuration functionality defined at the properties.
8 * <br/>
9 * The <code>com.sourceforge.jpatterns.core.configuration.PropertiesBasedFactory</code> class contains the getter returning the
10 * implementation of the <code>IPropertiesManager</code>. It is the single place where the configuration specifying which implementation
11 * of the interface should be used is configured at the Java Sources. All the configuration settings necessary for implementing the
12 * "factory" pattern is placed at the properties file, and then the JPatterns built-in pattern "factory" and xml configuration is used
13 * later for retrieving the implementations of the interfaces.
14 * <br/>
15 * Please review <code>com.sourceforge.jpatterns.core.configuration.PropertiesBasedFactory#getPropertiesManager()</code>
16 * <br/>
17 * Please review properly the following Java Docs - it is important for understanding of the algorithm of working of the JPatterns
18 * configuration functionality.
19 * {@link com.sourceforge.jpatterns.core.configuration.PropertiesProvider.JPProperties.USE_ONLY_CUSTOM_FRAMEWORK_PROPERTIES}
20 *
21 * todo [zmicer]: not sure if all these methods should take place here (e.g. getDefaultBundle etc)
22 *
23 * $Author:: zmicer $<br/>
24 * $Rev:: 67 $<br/> * $Date:: 2007-08-28 21:37:07 #$<br/>
25 * $Date:: 2007-08-28 21:37:07 #$<br/>
26 */
27 public interface IPropertiesManager extends Serializable
28 {
29 /**
30 * @return true if the custom resource bundle is presents at the class path
31 */
32 boolean customConfigPresents();
33
34 /**
35 * @return true if the default config resource bundle is presents at the class path
36 */
37 boolean defaultConfigPresents();
38
39 /**
40 * This method returns the value of the props signing if custom properties file totally overrides the default, and if it is present,
41 * then the values from the default properties are not used at all.
42 * <br/>
43 * Please review properly the following Java Docs - it is important for understanding of the algorithm of working of the JPatterns
44 * configuration functionality.
45 * {@link com.sourceforge.jpatterns.core.configuration.PropertiesProvider.JPProperties.USE_ONLY_CUSTOM_FRAMEWORK_PROPERTIES}
46 *
47 * @return true if the approrpiate property is set to the true, false otherwise.
48 */
49 boolean useOnlyCustomConfigIfPresent();
50
51 /**
52 * Return the bundle value using the ResourceBundle already retrieved. This method analyzes two bundles - default and custom one,
53 * the priority has custom - it provides the user with the possibility to override the values defined at the default properties,
54 * and it is a good customization point for the framework.
55 * <br/>
56 *
57 * @param key for the value we need. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
58 *
59 * @return the value for this bundle or just null in the case there is not defined bundles with such name
60 */
61 String getBundle(final String key);
62
63 /**
64 * Get bundle for the provided key - it is a class. The shorten name is used - Serializable, PropertiesManagerImpl etc. - without packaging
65 *
66 * @param key for the value we need, Class object. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
67 *
68 * @return the value for this bundle or just null in the case there is not defined bundles with such name
69 */
70 String getBundle(final Class key);
71
72 /**
73 * Get bundled object by the key provided. We would obtain the full class name using this key, and then try to instantiate the object.
74 * In the case value for the this key is null, or object can not be instantiated the <code>JPConfigException</code>
75 * would appear.
76 *
77 * @param key the class for which we should obtain appropriate implementation (usually it is class of the interface of abstract class
78 * implementation of which we would obtain.)
79 * @return the Object which was instantiated (following the Java Docs above we would throw the JPConfigException exception in
80 * the case the key was not found or the object can not be instantiated.)
81 */
82 Object getBundledObject(final Class key);
83
84 /**
85 * Get bundled object by the String key provided. We would obtain the full class name using this key, and then try to instantiate
86 * the object. In the case value for the this key is null, or object can not be instantiated the
87 * <code>JPConfigException</code> would appear.
88 *
89 * @param key the class for which we should obtain appropriate implementation (usually it is String - base name of the interface of
90 * abstract class implementation of which we would obtain.)
91 * @return the Object which was instantiated (following the Java Docs above we would throw the JPConfigException exception in
92 * the case the key was not found or the object can not be instantiated.)
93 */
94 Object getBundledObject(final String key);
95
96 /**
97 * Get the value from the default bundle. this was provided in any case - potentially it could be used at the unit tests etc.
98 * <br/>
99 * Please be noticed that we should check if the default configuration presents before the getting the value. The absence of the default
100 * configuration is a failure for the JPatterns framework.
101 *
102 * @param key to be processed. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
103 *
104 * @return String, the value required
105 */
106 String getDefaultBundle(final String key);
107
108 /**
109 * Get the value from the custom bundle. this was provided in any case - potentially it could be used at the unit tests etc.
110 * <br/>
111 * Please be noticed that we should check if the custom configuration presents before the getting the value.
112 * The absence of the custom configuration is a normal behavioral of the system.
113 *
114 * @param key to be processed. Can not be null (otherwise <code>IllegalArgumentException</code> would appear).
115 *
116 * @return String, the value required
117 */
118 String getCustomBundle(final String key);
119
120 /**
121 * @return the Enumeration of the keys (merged one or the custom one or the default one - it depends on the following:
122 * a. if custom properties files is present or was specified at the JVM parameter b. study the
123 * <code>com.sourceforge.jpatterns.core.configuration.PropertiesProvider.JPProperties.USE_ONLY_CUSTOM_FRAMEWORK_PROPERTIES</code>)
124 */
125 Set<String> getMergedKeys();
126 }