root/trunk/src/java/org/jcoderz/commons/config/package.xml

Revision 1011, 9.9 kB (checked in by amandel, 4 years ago)

Aligned svn keyword settings.
  • Property svn:mime-type set to text/xml
  • Property svn:eol-style set to native
Line 
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>
Note: See TracBrowser for help on using the browser.