Project Report: fawkez

Packagesummary org.jcoderz.commons.config

org.jcoderz.commons.config.package.xml

LineHitsNoteSource
1  <body>
2  <section>
3  <title>Overview</title>
4  <p>
5     The Configuration Service provides the usage and maintenance of
6     configuration.
7  </p>
8  <p>
9     A service of a Application uses the Configuration Service to get access
10     to its configuration data.
11  </p>
12  <p>
13     The functionality this component offers are:
14     <ul>
15        <li>providing a well formed and typed interface for other services, </li>
16        <li>reading the configuration data from the database
17            (or a Resource Bundle File), </li>
18        <li>caching the configuration data in order to provide fast access.</li>
19     </ul>
20  </p>
21  
22  <p>
23     The current version implementation does not provide
24     <ul>
25        <li>manipulation of configuration data, </li>
26        <li>updating the internal cache if the configuration data has been changed
27            by an administrator, </li>
28        <li>notifying the other services about cache updates (MultiCast or JMS)
29            using Read Mostly Pattern.</li>
30     </ul>
31     The modification and update feature is planned for the next release.
32  </p>
33  </section>
34  
35  <section>
36  <title>Key Requirements</title>
37  <p>
38     There are some key requirements and system constraints that have a
39     significant bearing on the architecture for the Configuration Service.
40     <ul>
41        <li>The main goal is the unified handling of service configuration.</li>
42        <li>Very fast modification of service parameters is essential.</li>
43        <li>Provide service configuration capabilities without burdening the
44            application.</li>
45        <li>The Configuration Service should be maintained via the
46            AdministrationService.</li>
47        <li>Reduce code complexity and maintenance efforts by using code
48            generation.</li>
49        <li>A kind of 'commit/rollback' mechanism should be provided.
50            [planned]</li>
51        <li>Configuration changes should be consistent over multiple, concurrent
52            application server lines and carried out simultaneous over all
53            application server lines. [planned]</li>
54        <li>Every configuration modification has to be logged in order to allow
55            back tracing. This has to be carried out by the AdministrationService
56            and not by the ConfigurationService. [planned]</li>
57        <li>An update is carried out simultaneously over all application
58            server lines. [planned]</li>
59        <li>Usage of Container Managed Persistency for most Entity Beans</li>
60        <li>Usage of Type-safe, well-formed and well-checkable Interface
61            Parameter-Types</li>
62     </ul>
63  </p>
64  </section>
65  
66  <section>
67  <title>Logical View</title>
68  <p>
69     The Commons Configuration Service is an internal component that is used
70     by Applications.
71  </p>
72  <p>
73     The Configuration Service uses the jCoderZ Service Framework where the
74     administration part and the online service part are each represented by a
75     Stateless Session Bean. An Administration Interface and Service Interface
76     must be implemented.
77  </p>
78  <p>
79     The following classes are derived from the service framework pattern:
80     <ul>
81        <li>ConfigurationServiceAdminBean</li>
82        <li>ConfigurationServiceAdminInterface</li>
83        <li>ConfigurationServiceBean</li>
84        <li>ConfigurationServiceInterface</li>
85        <li>ConfiguratonServiceCommonInterface</li>
86        <li>ConfigurationServiceClientFactory (generated by XSLT)</li>
87        <li>ConfigurationServiceContainerFactory (generated by XSLT)</li>
88        <li>ConfigurationServiceException (generated by XSLT)</li>
89     </ul>
90  </p>
91  <p>
92     The common configuration interface ConfiguratonServiceCommonInterface is
93     defined to provide common methods to both the online and administration
94     interface by extending this common interface, and extending its
95     implementation.
96  <diagram type="class" name="ConfigurationServiceInterface">
97     <class name="org.jcoderz.commons.config.ConfigurationServiceCommonInterface"/>
98     <class name="org.jcoderz.commons.config.ConfigurationServiceAdminInterface"/>
99     <class name="org.jcoderz.commons.config.ConfigurationServiceInterface"/>
100     <class name="org.jcoderz.commons.config.ConfigurationServiceCommonImpl"/>
101     <class name="org.jcoderz.commons.config.ConfigurationServiceAdminImpl"/>
102     <class name="org.jcoderz.commons.config.ConfigurationServiceImpl"/>
103     <description>
104     The Configuration Service service interface.
105     </description>
106  </diagram>
107  </p>
108  
109  <section>
110  <title>ConfigurationCacheInterface and its implementations</title>
111  <p>
112     A data access layer is built by providing a general Interface
113     ConfigurationCacheInterface, that can be implemented for different backend
114     resources like a database or a Java resource property file.
115  </p>
116  <p>
117     The class ConfigurationCacheByDbReadOnlyImpl represents an implementation
118     where the configuration data is stored within a database table.
119     The class ConfigurationCacheByPropertesImpl represents an implementation
120     where the configuration data is stored within a java property file.
121  <diagram type="class" name="ConfigurationServiceCache">
122     <class name="org.jcoderz.commons.config.ConfigurationCacheInterface"/>
123     <class name="org.jcoderz.commons.config.ConfigurationCacheByDbReadOnlyImpl"/>
124     <class name="org.jcoderz.commons.config.ConfigurationCacheByPropertiesImpl"/>
125     <description>
126     The basic classes of the Configuration Service (cache).
127     </description>
128  </diagram>
129  </p>
130  </section>
131  
132  <section>
133  <title>ConfigurationListener, ConfigCacheUpdateEvent</title>
134  <p>
135     An update mechanism is already prepared with help of ConfigurationListener
136     and ConfigUpdateEvent.
137  </p>
138  </section>
139  
140  <section>
141  <title>ContainerFactory, ClientFactory, ServiceConfiguration</title>
142  <p>
143     The service specific *Service*ContainerFactory and *Service*ClientFactory
144     provide factory methods to create a configuration object with a wellformed
145     and typed interface for this service by implementing the
146     *Service*Configuration interface.
147  </p>
148  <p>
149     These typed interfaces that are related to its specific service must be used
150     in a service to get access to its configuration data.
151  </p>
152  <p>
153     All these classes are generated by XSLT (ConfigurationClassesGenerator)
154     from the service declaration app-info.xml and the included
155     *service*-info.xml files (group tag, service attribute, and
156     configEntry tags).
157  </p>
158  </section>
159  </section>
160  
161  <section>
162  <title>Implementation View</title>
163  <p>
164     Beside to the Configuration Service Interface description, some
165     implementation specific details are given.
166  </p>
167  <section>
168  <title>Configuration Entry Declaration</title>
169  <p>
170     The needed configuration parameters are declared within the specific service
171     declaration by a XML structure.
172     For each configuration parameter its name, a description, the type
173     (Java type), serialization and deserialization methods, a default value,
174     and roles, which are allowed to modify values, can be specified.
175  </p>
176  <p>
177     In the current implementation the roles features is not supported, because in
178     the first release no configuration value modification is possible.
179     The modification feature is planned for future releases.
180  </p>
181  <p>
182     The declared type is used for the wellformed and typed
183     *Service*Configuration interface. The generated classes do perform the
184     necessary type conversions from the primitive type String used in the dabase
185     layer with help of the serialization and deserialization methods.
186  </p>
187  </section>
188  
189  <section>
190  <title>Usage</title>
191  <p>
192     In order to increase the performance, every service should only create its
193     *Service*Configuration instance once. Thus the configuration data is read
194     only once into the data cache.
195  
196     Example from Security Service:
197     <pre>
198   /** the cached instance of the service configuration */
199   private SecurityServiceConfiguration mConfig;
200  
201   /**
202    * Get the config instance.
203    * @return the SecurityServiceConfiguration instance
204    */
205   private final SecurityServiceConfiguration getConfig ()
206   {
207      if (mConfig == null)
208      {
209         mConfig
210               = SecurityServiceContainerFactory.getLocalServiceConfiguration();
211      }
212      return mConfig;
213   }
214     </pre>
215  </p>
216  <p>
217  <diagram type="class" name="ConfigurationServiceSample">
218     <!--<class name="org.jcoderz.commons.config.ConfigurationListener"/>
219     <class name="org.jcoderz.commons.config.ConfigUpdateEvent"/>
220     -->
221     <class name="org.jcoderz.commons.connector.ConnectorConfiguration"/>
222     <class name="org.jcoderz.commons.connector.ConnectorConfigurationImpl"/>
223     <class name="org.jcoderz.commons.connector.ConnectorConfigurationKeys"/>
224     <description>
225     Sample. Generated classes.
226     </description>
227  </diagram>
228  </p>
229  </section>
230  
231  <section>
232  <title>Read Only Bean for Database Access Layer</title>
233  <p>
234     The database access layer is implemented with help of
235     CMP Read Only EntityBeans, which are provided by BEA Weblogic.
236  
237     Beside the common CMP EntityBean, a second ReadOnly EntityBean is
238     additionally declared and used in the ConfigurationCacheByDbReadOnlyImpl
239     implementation. The ConfigEntityHelper provides its finder method in two
240     characteristics, to return the read and writable ConfigEntity objects and to
241     return the read-only ConfigReaderEntity objects.
242  
243     The ReadOnly EntityBean ConfigReaderEntity is generated with the ant target
244     add-readonly-entities and its task make-readonly-beans defined in build.xml.
245  </p>
246  </section>
247  
248  <section>
249  <title>API</title>
250  
251     <apidoc name="config">
252        <class name="org.jcoderz.commons.config.ConfigurationServiceCommonInterface"/>
253        <class name="org.jcoderz.commons.config.ConfigurationServiceAdminInterface"/>
254        <class name="org.jcoderz.commons.config.ConfigurationServiceInterface"/>
255        <class name="org.jcoderz.commons.config.ConfigurationServiceCommonImpl"/>
256        <class name="org.jcoderz.commons.config.ConfigurationServiceAdminImpl"/>
257        <class name="org.jcoderz.commons.config.ConfigurationServiceImpl"/>
258     </apidoc>
259  </section>
260  
261  <section>
262  <title>Database Schema</title>
263  </section>
264  <diagram type="ER" name="cfgSchema" file="src/sql/cfg_create_tables.sql">
265     <description>
266     ER-Diagram of the configuration service.
267     </description>
268  </diagram>
269  </section>
270  </body>

Findings in this File