docs/3.0/customizing-configuration.html

Title: Customizing Configuration

	<P>A user can create her own subclass of Configuration and use it instead of the classes provided by Cayenne. Custom subclasses are usually created to load configuration files from non-standard locations, to automatically configure Cayenne during certain events that happen in deployment containers, etc. Cayenne provides a few implementations of Configuration discussed later in this chapter.</P>

<P>To ensure that Cayenne uses the correct Configuration class, it must be initialized properly before any calls to Configuration are made:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">import</SPAN> org.apache.cayenne.conf.Configuration
...
<SPAN class="code-object">Class</SPAN> myConfigSubclass = my.<SPAN class="code-keyword">package</SPAN>.ConfigSubclass.class;
Configuration.initializeSharedConfiguration(myConfigSubclass);
</PRE>
</DIV></DIV>
<P>After this code is executed, any subsequent calls to <TT>Configuration.getSharedConfiguration()</TT> will return an instance of the custom class instead of <TT>DefaultConfiguration</TT>.</P>

<P>Another useful feature is the customization of the resource lookup strategy implemented by the existing classes. Currently, both <TT>DefaultConfiguration</TT> and <TT>FileConfiguration</TT> offer the possibility to add additional paths which will be searched for resources.</P>

<H3><A name="CustomizingConfiguration-DefaultConfiguration"></A>DefaultConfiguration</H3>

<P><TT>DefaultConfiguration</TT> uses the application's class path for locating configuration files; this works for both &quot;expanded&quot; class paths and JAR files. &quot;Out of the box&quot; only resources on the top level of the class path are found; very often it is convenient to have a subdirectory ('package') with configuration files. There are two ways to make Configuration find these files:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">import</SPAN> org.apache.cayenne.conf.DefaultConfiguration;
...
DefaultConfiguration conf = <SPAN class="code-keyword">new</SPAN> DefaultConfiguration();			
conf.addClassPath(<SPAN class="code-quote">&quot;my/<SPAN class="code-keyword">package</SPAN>/conf&quot;</SPAN>);
Configuration.initializeSharedConfiguration(conf);
</PRE>
</DIV></DIV>
<P>Alternatively you can place an empty subclass of DefaultConfiguration into your package and use that class directly:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">import</SPAN> my.<SPAN class="code-keyword">package</SPAN>.conf.MyPackageConfiguration;
...
Configuration.initializeSharedConfiguration(<SPAN class="code-keyword">new</SPAN> MyPackageConfiguration());
</PRE>
</DIV></DIV>

<H3><A name="CustomizingConfiguration-FileConfiguration"></A>FileConfiguration</H3>

<P><TT>FileConfiguration</TT> uses the regular file system to load its files, and works very silimar to <TT>DefaultConfiguration</TT>:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">import</SPAN> org.apache.cayenne.conf.FileConfiguration;
...
<SPAN class="code-object">String</SPAN> fileName = <SPAN class="code-quote">&quot;/some/path/to/my-cayenne.xml&quot;</SPAN>;
FileConfiguration conf = <SPAN class="code-keyword">new</SPAN> FileConfiguration(<SPAN class="code-keyword">new</SPAN> File(fileName));
Configuration.initializeSharedConfiguration(conf);
</PRE>
</DIV></DIV>
<P>The fileName argument can be absolute or relative to the application's working directory, and is checked for accessibility. A more flexible lookup can be done by using the name without any path and adding search paths:</P>
<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">
<SPAN class="code-keyword">import</SPAN> org.apache.cayenne.conf.FileConfiguration;
...
FileConfiguration conf = <SPAN class="code-keyword">new</SPAN> FileConfiguration(<SPAN class="code-quote">&quot;my-cayenne.xml&quot;</SPAN>);
conf.addFilesystemPath(<SPAN class="code-quote">&quot;a/relative/path&quot;</SPAN>);
conf.addFilesystemPath(<SPAN class="code-quote">&quot;/another/absolute/path&quot;</SPAN>);
conf.addFilesystemPath(<SPAN class="code-keyword">new</SPAN> File(<SPAN class="code-quote">&quot;/some/path/that/must/exist/&quot;</SPAN>));
Configuration.initializeSharedConfiguration(conf);
</PRE>
</DIV></DIV>
<P>The difference between the String and File arguments is that the latter are checked for existence. Both variants can be absolute or relative, and are evaluated in the order in which they are added to the Configuration.</P>