Spring/spring-net
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add VariableSource configuration sections to documentation

Browse Source
This commit is contained in:
Marijn van der Zee
2011-12-16 17:40:16 +01:00
parent 6b05570040
commit 6d934ba9e4
1 changed files with 244 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
doc/reference/src/objects.xml
View File

@@ -4996,24 +4996,259 @@ cfg.PostProcessObjectFactory(factory);</programlisting></para>
&lt;/object&gt;
&lt;/list&gt;
&lt;/property&gt;
&lt;/object&gt;
</programlisting><note>
&lt;/object&gt; </programlisting><note>
<para>The use of the <property>IgnoreMissingResources</property>
property above will mean that if the property file is not found it
will be silently ignored and the resolution will continue to
<classname>ConfigSectionVariableSource</classname>.</para>
</note>The IVariableSource interface is shown below</para>
</note></para>
<programlisting language="csharp">public interface IVariableSource
<para>The variable sources that Spring.NET provides out of the box are
described in the following sections.</para>
<sect4>
<title><literal>ConfigSectionVariableSource</literal></title>
<para>The <literal>ConfigSectionVariableSource</literal> allows you
to define variables in a custom configuration section in you
configuration file:</para>
<programlisting language="myxml">&lt;!-- app.config: --&gt;
&lt;configuration&gt;
&lt;configSections&gt;
&lt;section name="DonConfiguration" type="System.Configuration.NameValueSectionHandler"/&gt;
&lt;/configSections&gt;
&lt;DonConfiguration&gt;
&lt;add key="don_name" value="Dick Whitman"/&gt;
&lt;add key="don_age" value="41" /&gt;
&lt;/DonConfiguration&gt;
&lt;/configuration&gt;
&lt;!-- consume variables: --&gt;
&lt;object type="Example.Person, Spring.IocQuickStart.VariableSources"&gt;
&lt;property name="Name" value="${don_name}" /&gt;
&lt;property name="Age" value="${don_age}" /&gt;
&lt;/object&gt;
&lt;!-- VariableSource configuration: --&gt;
&lt;object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"&gt;
&lt;property name="SectionNames" value="DonConfiguration" /&gt;
&lt;/object&gt;
</programlisting>
<para>This is similar to using the
<literal>PropertyPlaceHolderConfigurer</literal> described
above.</para>
<para>By simply configuring the appropriate section, you can use the
<literal>ConfigSectionVariableSource</literal> to retrieve variables
from application settings and user settings. Assuming your
application's root namespace is
<literal>Spring.IocQuickStart</literal>, then your application- and
user settings can be loaded as variables by configuring the
following variable sources:</para>
<programlisting language="myxml">&lt;!-- From .net's ApplicationSettings: --&gt;
&lt;object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"&gt;
&lt;property name="SectionNames" value="applicationSettings/Spring.IocQuickStart.Properties.Settings" /&gt;
&lt;/object&gt;
&lt;!-- From .net's UserSettings: --&gt;
&lt;object type="Spring.Objects.Factory.Config.ConfigSectionVariableSource, Spring.Core"&gt;
&lt;property name="SectionNames" value="userSettings/Spring.IocQuickStart.Properties.Settings" /&gt;
&lt;/object&gt;
</programlisting>
<para>If you configured your application settings as such:</para>
<para><mediaobject>
<imageobject>
<imagedata fileref="images/applicationsettings.png"></imagedata>
</imageobject>
</mediaobject>Then you can use <literal>${peggy_name}</literal>
and <literal>${peter_age}</literal> as variable placeholders in your
object definitions.</para>
</sect4>
<sect4>
<title><literal>PropertyFileVariableSource</literal></title>
<para>A <literal>PropertyFileVariableSource</literal> allows to read
properties defined in a Java-style property file as variables.
Assume a file named <literal>application.properties</literal> in
your application folder containing:</para>
<programlisting>joan_name=Joan Harris
joan_age=35</programlisting>
<para>You can use the <literal>${joan_name}</literal> and
<literal>${joan_age}</literal> variable placeholders if you
configure the following variable source:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.PropertyFileVariableSource, Spring.Core"&gt;
&lt;property name="Location" value="~\application.properties" /&gt;
&lt;/object&gt;</programlisting>
</sect4>
<sect4>
<title><literal>ConfigurableVariableSource</literal></title>
<para>A <literal>ConfigurableVariableSource</literal> allows you
define variables inline in a variable source definition. To
configure the variables <literal>midge_name</literal> and
<literal>midge_age</literal>, you can use the following
<literal>ConfigurableVariableSource</literal> definition:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.ConfigurableVariableSource, Spring.Core"&gt;
&lt;property name="Variables"&gt;
&lt;name-values&gt;
&lt;add key="midge_name" value="Midge Daniels"/&gt;
&lt;add key="midge_age" value="33"/&gt;
&lt;/name-values&gt;
&lt;/property&gt;
&lt;/object&gt;</programlisting>
</sect4>
<sect4>
<title><literal>CommandLineArgsVariableSource</literal></title>
<para>You can use commandline arguments as a source for variables.
Assume you issue the following command to start myapp:</para>
<para><programlisting>myapp /roger_name:"Roger Sterling" /roger_age:57</programlisting></para>
<para>The following variable source configuration allows you to use
<literal>${roger_name}</literal> and <literal>${roger_age}</literal>
as variable placeholders:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.CommandLineArgsVariableSource, Spring.Core"&gt;
&lt;property name="ArgumentPrefix" value ="/" /&gt; &lt;!-- optional; default: "/" --&gt;
&lt;property name="ValueSeparator" value=":" /&gt; &lt;!-- optional; default: ":" --&gt;
&lt;/object&gt;</programlisting>
</sect4>
<sect4>
<title><literal>RegistryVariableSource</literal></title>
<para>Entries in the Windows registry can be used as variables. When
your registry contains the key
<literal>HKEY_CURRENT_USER\MyKey</literal> with entries
<literal>freddy_name (String)</literal> and <literal>freddy_age
(DWord)</literal>, then you can configure the following variable
source to use <literal>freddy_name</literal> and
<literal>freddy_age</literal> as variables:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.RegistryVariableSource, Spring.Core"&gt;
&lt;property name="Key" value="HKEY_CURRENT_USER\MyKey" /&gt;
&lt;/object&gt;</programlisting>
</sect4>
<sect4>
<title><literal>EnvironmentVariableSource</literal></title>
<para>You can configure an
<literal>EnvironmentVariableSource</literal> an to retrieve
variables from environment variables available through <link
ns6:href="http://msdn.microsoft.com/en-us/library/system.environment.aspx">.NET's
<literal>System.Environment</literal> class</link>:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.EnvironmentVariableSource, Spring.Core" /&gt;
</programlisting>
<para>To retrieve a value for a variable named
<literal>ken_name</literal>, the
<literal>EnvironmentVariableSource</literal> will directly call
<literal>System.Environment.GetEnvironmentVariable("ken_name")</literal>.</para>
</sect4>
<sect4>
<title><literal>ConnectionStringsVariableSource</literal></title>
<para>Visual Studio has good support for configuring database
connection strings in a <literal>connectionStrings</literal> section
in you application configuration file. You can retrieve these
connections as variables by configuring a
<literal>ConnectionStringsVariableSource</literal>:</para>
<programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.ConnectionStringsVariableSource, Spring.Core" /&gt;</programlisting>
<para>Assume the following connection string section in your
application configuration file:</para>
<programlisting language="myxml">&lt;connectionStrings&gt;
&lt;add name="myConnection"
connectionString="Data Source=myserver;Integrated Security=True;..."
providerName="System.Data.SqlClient" /&gt;
&lt;/connectionStrings&gt;</programlisting>
<para>Then you would use the variables as in following object
definition: </para>
<programlisting language="myxml">&lt;object type="Example.MyClass, MyAssembly"&gt;
&lt;property name="ConnectionString" value="${myConnection.connectionString}" /&gt;
&lt;property name="ProviderName" value="${myConnection.providerName}" /&gt;
&lt;/object&gt; </programlisting>
<para><note>
<para>Append ".connectionString" to the connection name to get
the connection string and append ".providerName" to the
connection name to get the provider name.</para>
</note><note>
<para>When adding a connection using Visual Studio's application
settings, your connection will be named similar to
<literal>MyNamespace.Properties.Settings.myConnection</literal>
and the corresponding variable name for the connection string
would become
<literal>MyNamespace.Properties.Settings.myConnection.connectionString</literal>.
</para>
</note></para>
</sect4>
<sect4>
<title><literal>SpecialFolderVariableSource</literal></title>
<para>The <literal>SpecialFolderVariableSource</literal> resolves
the full path for variable names against special folders as defined
by the <literal>System.Environment.SpecialFolder</literal>
enumeration. Add it to your variable sources as:</para>
<para><programlisting language="myxml">&lt;object type="Spring.Objects.Factory.Config.SpecialFolderVariableSource, Spring.Core" /&gt;</programlisting></para>
<para>Now you can inject the full path to the current user's
desktop, or to this machine's program files folders:</para>
<programlisting language="myxml">&lt;object id="specials" type="Example.Specials, Spring.IocQuickStart.VariableSources"&gt;
&lt;property name="FullPathToDesktop" value="${Desktop}" /&gt;
&lt;property name="FullPathToPrgramFiles" value="${ProgramFiles}" /&gt;
&lt;/object&gt;</programlisting>
<para>Any entry in the <link
ns6:href="http://msdn.microsoft.com/library/system.environment.specialfolder.aspx">System.Environment.SpecialFolder</link>
enumeration can be used as a variable name. </para>
</sect4>
<sect4>
<title>Custom <literal>IVariableSource</literal>
implementations</title>
<para>The <literal>IVariableSource</literal> is the base interface
for providing the ability to get the value of property placeholders
(name-value) pairs from a variety of sources. The IVariableSource
interface is shown below:</para>
<programlisting language="csharp">public interface IVariableSource
{
bool CanResolveVariable(string name);
string ResolveVariable(string name);
}</programlisting>
<para>This is a simple contract to implement if you should decide to
create your own custom implemention. Look at the source code of the
current implementations for some inspiration if you go that route. To
register your own custom implemenation, simply configure
VariablePlaceholderConfigurer to refer to your class.</para>
<para>This is a simple contract to implement if you should decide to
create your own custom implemention. Look at the source code of the
current implementations for some inspiration if you go that route.
To register your own custom implemenation, simply configure
<literal>VariablePlaceholderConfigurer</literal> to refer to your
class.</para>
</sect4>
</sect3>
</sect2>