(Available in 1.0)
The Spring.Core assembly provides the basis for
the Spring.NET Inversion of Control (IoC - sometimes also referred to as
Dependency Injection) features (see Section 3.1, “Inversion of Control” for
some additional material describing this software engineering principle).
The IObjectFactory
interface from the Spring.Core assembly provides an
advanced configuration mechanism capable of managing objects of any
nature, using potentially any kind of storage facility. The
IApplicationContext
interface from the same assembly builds on top of the functionality
provided by the IObjectFactory interface,
complementing it with features such as integration with Spring.NET's
Aspect Oriented Programming (AOP) features and message resource handling
(for use in internationalization).
In short, the IObjectFactory provides the
configuration framework and basic functionality, while the
IApplicationContext adds more enterprise-centric
functionality to it. In general, the
IApplicationContext is a complete superset of the
IObjectFactory, and any description of
IObjectFactory capabilities and behavior should be
considered to apply to IApplicationContexts as
well.
This chapter is divided into two parts, with the first part covering
the basic principles that apply to both the
IObjectFactory and
IApplicationContext, with the second part covering
those features that apply only to the
IApplicationContext interface.
If you are new to Spring.NET or IoC containers in general, you may want to consider starting with Chapter 27, IoC Quickstarts, which contains a number of introductory level examples that actually demonstrate a lot of what is described in detail below. Don't worry if you don't absorb everything at once... those examples serve only to paint a picture of how Spring.NET hangs together in really broad brushstrokes. Once you have finished with those examples, you can come back to this section which will fill in all the fine detail.
The IObjectFactory is the actual container
that instantiates, configures, and manages a number of objects. These
objects typically collaborate with one another, and thus can be said to
have dependencies between themselves. These dependencies are reflected
in the configuration data used by the
IObjectFactory (although some dependencies may
not be visible as configuration data, but rather be a function of
programmatic interactions between objects at runtime).
An IObjectFactory is represented by the
Spring.Objects.Factory.IObjectFactory interface,
of which there are multiple implementations. The most commonly used
simple IObjectFactory is the
Spring.Objects.Factory.Xml.XmlObjectFactory.
Interaction with the IObjectFactory interface is
discussed in Section 4.7, “Interacting with the IObjectFactory”. Additional
features offered by the IApplicationContext are
discussed in section Section 4.11, “Introduction to the
IApplicationContext”.
As mentioned previously in the introduction, one of the central
tenets of the Spring.NET framework is non-invasiveness. Quite simply,
your application code should not depend on any of the Spring.NET APIs.
However, if one is going to take advantage of the features provided by
Spring.NET's IoC container, through the use of either the
IObjectFactory or the
Spring.Context.IApplicationContext interfaces, at
some point one has to instantiate an
appropriate implementation of either of these two core interfaces. This
can happen explicitly in user code via the use of the
new operator (in C# - VB.NET developers have the
equivalent New operator); or more easily by using a
custom configuration section in the standard .NET application (or web)
configuration file. Once the container has been created you may never
need to explicitly interact with it again in your code.
What follows are some examples of how one can instantiate an
actual implementation of the IObjectFactory
interface. In the following example an object factory, complete with
object definitions describing the services that we want to wire up and
expose, is created from the contents of the
objects.xml file; this file is passed in as an
argument to one of the constructors of the
XmlObjectFactory class.
[C#]
IResource input = new FileSystemResource ("objects.xml");
IObjectFactory factory = new XmlObjectFactory(input);The above example uses Spring.NET's IResource
abstraction. The IResource interface provides a
simple and uniform interface to a wide array of IO resources that can
represent themselves as System.IO.Streams. The
IResource abstraction is explained further in
Section 6.1, “Introduction”. These resources are most
frequently files or URLs but can also be resources that have been
embedded inside a .NET assembly. A simple URI syntax is used to describe
the location of the resource, which follows the standard conventions for
files, i.e. file://object.xml and other well known
protocols such as http.
As previously mentioned, one is more likely to use the
IApplicationContext interface. Any of the
IApplicationContext implementations can be
instantiated explicitly by specifying IResource
URI locations to the constructor. Multiple configuration files can used
to construct an IApplicationContext as shown
below.
IApplicationContext context = new XmlApplicationContext( "file://objects.xml", "assembly://MyAssembly/MyProject/objects-dal-layer.xml"); // of course, an IApplicationContext is also an IObjectFactory... IObjectFactory factory = (IObjectFactory) context;
The
following snippet shows the use of the URI syntax for referring to a
resource that has been embedded inside a .NET assembly,
assembly://<AssemblyName>/<NameSpace>/<ResourceName>
![[Note]](../images/admons/note.png) | Note |
|---|---|
| To create an embedded resource using Visual Studio you must set the Build Action of the .xml configuration file to Embedded Resource in the file property editor. Also, you will need to explicitly rebuild the project containing the configuration file if it is the only change you make between successive builds. If using NAnt to build, add a <resources> section to the csc task. For example usage, look at the Spring.Core.Tests.build file included the distribution. |
The preferred way to create an
IApplicationContext or
IObjectFactory is to use a custom configuration
section in the standard .NET application configuration file (one of
App.config or Web.config). A
custom configuration section that creates the same
IApplicationContext as the previous example is
<spring>
<context type="Spring.Context.Support.XmlApplicationContext, Spring.Core">
<resource uri="file://objects.xml"/>
<resource uri="assembly://MyAssembly/MyProject/objects-dal-layer.xml"/>
</context>
</spring> The context type (specified as the value of
the type attribute of the context
element) is wholly optional, and defaults to the
Spring.Context.Support.XmlApplicationContext
class, so the following XML snippet is functionally equivalent to the
first.
<spring>
<context>
<resource uri="file://objects.xml"/>
<resource uri="assembly://MyAssembly/MyProject/objects-dal-layer.xml"/>
</context>
</spring> To acquire a reference to an
IApplicationContext using a custom configuration
section, one simply uses the following code; please note that the string
literal 'spring/context' is not arbitrary... you
must use this string value (a constant
is available in the AbstractApplicationContext
class).
IApplicationContext ctx
= ContextRegistry.GetContext(); The
ContextRegistry is used to both instantiate the
application context and to perform service locator style access to other
objects. (See Section 4.16, “Service Locator access” for more
information). The glue that makes this possible is an implementation of
the Base Class Library (BCL) provided
IConfigurationSectionHandler interface, namely
the Spring.Context.Support.ContextHandler class.
The handler class needs to be registered in the
configSections section of the .NET configuration file
as shown below.
<configSections>
<sectionGroup name="spring">
<section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
</sectionGroup>
</configSections> This declaration now enables the use
of a custom context section starting at the spring
root element.
In some usage scenarios, user code will not have to explicitly
instantiate an appropriate implementation of the
IObjectFactory interface, since Spring.NET code
will do it. For example, the ASP.NET web layer provides support code to
load a Spring.NET IApplicationContext
automatically as part of the normal startup process of an ASP.NET web
application. Similar support for WinForms applications is being
investigated.
While programmatic manipulation of
IObjectFactory instances will be described later, the
following sections will concentrate on describing the configuration of
objects managed by IObjectFactory instances.
An IObjectFactory configuration consists
of, at its most basic level, definitions of one or more objects that the
IObjectFactory will manage. In an XML based
factory these are defined as one or more object
elements inside a top-level objects element. The
top-level name must be objects.
<objects xmlns="http://www.springframework.net" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.net http://www.springframework.net/xsd/spring-objects.xsd"> <object id="..." type="..."> ... </object> <object id="...." type="..."> ... </object> ... </objects>
Spring.NET comes with an XSD schema to make the validation of the
XML object definitions a whole lot easier. The XSD document is
thoroughly documented so feel free to take a peak inside (see Appendix A, Spring.NET's spring-objects.xsd). The XSD is currently used in the
implementation code to validate the XML document. The XSD schema serves
a dual purpose in that it also facilitates the editing of XML object
definitions inside an XSD aware editor (typically VisualStudio.NET) by
providing validation (and Intellisense support in the case of
VisualStudio.NET). You may wish to refer to Chapter 26, Visual Studio.NET Integration for
more information regarding such integration. You can also obtain the XSD
that supports the latest release from the web at spring-objects.xsd.
Your XML object definitions can also be defined within the
standard .NET application configuration file by registering the
Spring.Context.Support.DefaultSectionHandler
class as the configuration section handler for inline object
definitions. This allows you to completely configure one or more
IApplicationContext instances within a single
standard .NET application configuration file as shown in the following
example.
<configuration>
<configSections>
<sectionGroup name="spring">
<section name="context" type="Spring.Context.Support.ContextHandler, Spring.Core"/>
<section name="objects" type="Spring.Context.Support.DefaultSectionHandler, Spring.Core" />
</sectionGroup>
</configSections>
<spring>
<context>
<resource uri="config://spring/objects"/>
</context>
<objects xmlns="http://www.springframework.net">
...
</objects>
</spring>
</configuration>Other options available to structure the configuration files are described in Section 4.13.1, “Context Hierarchies” and Section 4.15, “Importing Object Definitions from One File Into Another”.
The IApplicationContext can be configured
to register other resource handlers, custom parsers to integrate
user-contributed XML schema into the object definitions section, type
converters, and define type aliases. These features are discussed in
section Section 4.12, “Configuration of IApplicationContext”
Object definitions describe objects managed by an
IObjectFactory or
IApplicationContext. Object definitions contain
the following information:
The object type, which is the actual implementation class
(the .NET System.Type) of the object being
described in the object definition.
Object behavioral configuration elements, which state how the object should behave in the Spring.NET IoC container (i.e. prototype or singleton, autowiring mode, dependency checking mode, initialization and destruction methods).
Property values to set in the newly created object. An example would be the number of threads to use in an object that manages a worker thread pool (either specified as a property or as a constructor argument), or the System.Type that should be used to create the thread pool.
Other objects your object needs to do its work, i.e. collaborators (also specified as properties or as constructor arguments). These can also be called dependencies.
In the list above, we mentioned the use of property setters and constructor arguments. Spring.NET supports two types of IoC: Type 2 and Type 3 (Constructor Dependency Injection and Setter Dependency Injection respectively). What that basically means is that when new objects are constructed by the IoC container you can set properties of the object using both regular property setters, and also directly as arguments that you specify to a constructor.
The concepts listed above directly translate to a set of elements the object definition consists of. These elements are listed below, along with a link to further documentation about each of them.
Table 4.1. Object definition explanation
| Feature | More info |
|---|---|
| type | Section 4.2.3, “Object Creation” |
| id and name | Section 4.2.5, “The object identifiers (id and
name)” |
| singleton or prototype | Section 4.2.6, “Singleton & Prototype Scope” |
| object properties | Section 4.3.1, “Setting object properties and collaborators” |
| constructor arguments | Section 4.3.1, “Setting object properties and collaborators” |
| autowiring mode | Section 4.3.8, “Autowiring collaborators” |
| dependency checking mode | Section 4.3.9, “Checking for dependencies” |
| initialization method | Section 4.5.1, “Lifecycle interfaces” |
| destruction method | Section 4.5.1, “Lifecycle interfaces” |
Every object definition needs to know the type (the .NET
System.Type) of the object being defined ( see
Section 4.2.3.3, “Object creation via an instance factory method”, and
Section 4.6, “Abstract and Child object definitions”for the exceptions). In the much
more common case where the IObjectFactory itself
directly creates the object instance by calling one of the objects
constructors the type attribute specifies the type of the object that is
to be instantiated. In the less common case where the
IObjectFactory calls a so-called factory method on a
type to create the object instance, the type attribute specifies the
actual type containing the factory method. The type of the object
returned from the invocation of this factory method may be the same
type, or another type entirely, it doesn't matter.
When creating an object using the constructor approach, there are no special requirements as to what this class is or how it is implemented (i.e. your class does not have to implement a special interface to make it Spring.NET compatible), other than the fact that it must not be an interface. Just specifying the object type (and the assembly into which it has been compiled) should be enough. However, depending on what type of IoC you are going to use for that specific object, you may need to create a default constructor (i.e. a constructor that has no parameters) in the source code definition of your class.
The XmlObjectFactory implementation of
the IObjectFactory interface can consume object
definitions that have been defined in XML, for example...
<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary"/>
This XML fragment describes an object definition that will be
identified by the exampleObject name, instances
of which will be of the Examples.ExampleObject
type that has been compiled into the
ExamplesLibrary assembly. Take special note of the
structure of the type attribute's value... the
namespace-qualified name of the class is specified, followed by a
comma, followed by (at a bare minimum) the name of the assembly that
contains the class. In the preceding example, the
ExampleObject class is defined in the
Examples namespace, and it has been compiled into
the ExamplesLibrary assembly.
The name of the assembly that contains the type
must be specified in the type
attribute. Furthermore, it is recommended that you specify the fully
qualified assembly name [1] in order to guarantee that the type that Spring.NET uses
to instantiate your object (s) is indeed the one that you expect.
Usually this is only an issue if you are using classes from (strongly
named) assemblies that have been installed into the Global Assembly
Cache (GAC).
If you have defined nested classes use the addition symbol, +,
to reference the nested class. For example, if the class
Examples.ExampleObject had a nested class
Person the XML declaration would be
<object id="exampleObject" type="Examples.ExampleObject+Person, ExamplesLibrary"/>
If you are defining classes that have been compiled into
assemblies that are available to your application (such as the
bin directory in the case of ASP.NET applications)
via the standard assembly probing mechanisms, then you can specify
simply the name of the assembly (e.g.
ExamplesLibrary.Data)... this way, when (or if) the
assemblies used by your application are updated, you won't have to
change the value of every <object/>
definition's type attribute to reflect the new
version number (if the version number has changed)... Spring.NET will
automatically locate and use the newer versions of your assemblies
(and their attendant classes) from that point forward.
When defining an object which is to be created using a static factory method, along with the type attribute which specifies the type containing the static factory method, another attribute named factory-method is needed to specify the name of the factory method itself. Spring.NET expects to be able to call this method (with an optional list of arguments as described later) and get back a live object, which from that point on is treated as if it had been created normally via a constructor. One use for such an object definition is to call static factories in legacy code.
Following is an example of an object definition which specifies
that the object is to be created by calling a factory-method. Note
that the definition does not specify the type (class) of the returned
object, only the type containing the factory method. In this example,
CreateInstance must be a static method.
<object id="exampleObject"
type="Examples.ExampleObjectFactory, ExamplesLibrary"
factory-method="CreateInstance"/>The mechanism for supplying (optional) arguments to the factory method, or setting properties of the object instance after it has been returned from the factory, will be described shortly.
Quite similar to using a static factory method to create an object, is the the use of an instance (non-static) factory method, where a factory method of an existing object from the factory is called to create the new object.
To use this mechanism, the type attribute must be left empty, and the factory-object attribute must specify the name of an object in the current or an ancestor object factory which contains the factory method. The factory method itself should still be set via the factory-method attribute.
Following is an example...
<!-- the factory object, which contains an instance method called 'CreateInstance' -->
<object id="exampleFactory" type="..."/>
<!-- the object that is to be created by the factory object -->
<object id="exampleObject"
factory-method="CreateInstance"
factory-object="exampleFactory"/>Although the mechanisms for setting object properties are still to be discussed, one implication of this approach is that the factory object itself can be managed and configured via Dependency Injection, by the container.
Generic types can also be created in much the same manner an non-generic types.
The following examples shows the definition of simple generic types and how they can be created in Spring's XML based configuration file.
namespace GenericsPlay
{
public class FilterableList<T>
{
private List<T> list;
private String name;
public List<T> Contents
{
get { return list; }
set { list = value; }
}
public String Name
{
get { return name; }
set { name = value; }
}
public List<T> ApplyFilter(string filterExpression)
{
/// should really apply filter to list ;)
return new List<T>();
}
}
}The XML configuration to create and configure this object is shown below
<object id="myFilteredIntList" type="GenericsPlay.FilterableList<int>, GenericsPlay"> <property name="Name" value="My Integer List"/> </object>
There are a few items to note in terms how to
specify a generic type. First, the left bracket that specifies the
generic type, i.e. <, is replaced with the
string < due to XML escape syntax for the less than symbol.
Yes, we all realize this is less than ideal from the readability point
of view. Second, the generic type arguments can not be fully assembly
qualified as the comma is used to seperate generic type arguments.
Alternative characters used to overcome the two quirks can be
implemented in the future but so far, all proposals don't seem to help
clarify the text. The suggested solution to improve readability is to
use type aliases as shown below.candidate
<typeAliases> <alias name="GenericDictionary" type=" System.Collections.Generic.Dictionary<,>" /> <alias name="myDictionary" type="System.Collections.Generic.Dictionary<int,string>" /> </typeAliases>
So that instead of something like this
<object id="myGenericObject"
type="GenericsPlay.ExampleGenericObject<System.Collections.Generic.Dictionary<int , string>>, GenericsPlay" />It can be shortened to
<object id="myOtherGenericObject"
type="GenericsPlay.ExampleGenericObject<GenericDictionary<int , string>>, GenericsPlay" />or even shorter
<object id="myOtherOtherGenericObject"
type="GenericsPlay.ExampleGenericObject<MyIntStringDictionary>, GenericsPlay" />
Refer to Section 4.12, “Configuration of IApplicationContext” for additional information on using type aliases.
The following classes are used to demonstrate the ability to create instances of generic types that themselves are created via a static generic factory method.
public class TestGenericObject<T, U>
{
public TestGenericObject()
{
}
private IList<T> someGenericList = new List<T>();
private IDictionary<string, U> someStringKeyedDictionary =
new Dictionary<string, U>();
public IList<T> SomeGenericList
{
get { return someGenericList; }
set { someGenericList = value; }
}
public IDictionary<string, U> SomeStringKeyedDictionary
{
get { return someStringKeyedDictionary; }
set { someStringKeyedDictionary = value; }
}
}The accompanying factory class is
public class TestGenericObjectFactory
{
public static TestGenericObject<V, W> StaticCreateInstance<V, W>()
{
return new TestGenericObject<V, W>();
}
public TestGenericObject<V, W> CreateInstance<V, W>()
{
return new TestGenericObject<V, W>();
}
}
The XML snippit to create an instance of TestGenericObject
where V is a List of integers and
W is an integer is shown below
<object id="myTestGenericObject"
type="GenericsPlay.TestGenericObjectFactory, GenericsPlay"
factory-method="StaticCreateInstance<System.Collections.Generic.List<int>,int>"
/>The StaticCreateInstance method is responsible for instantiating the object that will be associated with the id 'myTestGenericObject'.
Using the class from the previous example the XML snippit to create an instance of a generic type via an instance factory method is shown below
<object id="exampleFactory" type="GenericsPlay.TestGenericObject<int,string>, GenericsPlay"/>
<object id="anotherTestGenericObject"
factory-object="exampleFactory"
factory-method="CreateInstance<System.Collections.Generic.List<int>,int>"/>
This creates an instance of
TestGenericObject<List<int>,int>
Every object has one or more ids (also called identifiers, or
names; these terms refer to the same thing). These ids must be unique
within the IObjectFactory or
IApplicationContext that the object definition is
hosted in. An object definition will almost always have only one id, but
if an object has more than one id, the extra ones can essentially be
considered aliases.
In an XML object definition, the id or
name attributes of the object
element are used to specify the object definition's id (s), and at least
one id must be specified in one or both of these attributes. The
id attribute allows you to specify one id, and since
it is marked in the Spring.NET XSD as a bona-fide XML element ID
attribute, the parser is able to do some extra validation when other
elements point back to this one. As such, it is the preferred way to
specify an object id. However, the XML specification does limit the
characters that are legal in XML IDs. This is usually not a constraint,
but if you have a need to use one of these characters, or want to
introduce aliases to the object, you may also or instead specify one or
more object ids (separated by a comma (,) or semicolon (;)) via the
name attribute.
Objects can be deployed in one of two modes: singleton or non-singleton (the latter is also called a prototype, although the term is used loosely as it doesn't quite fit). When an object definition is set to the singleton mode, only one shared instance of the object will be managed, and all requests for objects with an id or ids matching that object definition will result in that one specific object instance being returned (i.e. the object defined by the object definition will only ever be created once).
The non-singleton, prototype mode of an object deployment results in the creation of a new object instance every time a request for that specific object is received. For example, this is ideal for those situations where each user needs an independent user object or something similar.
Object definitions operate in singleton mode by default, unless you specify otherwise. Keep in mind that by changing the mode to non-singleton (prototype), each request for an object will result in a new instance and this might not be what you actually want. So only change the mode to prototype when absolutely necessary.
| Note |
|---|---|
When deploying an object in the prototype mode, the lifecycle of the object changes slightly. By definition, Spring.NET cannot manage the complete lifecycle of a non-singleton / prototype object, since after it is created, it is given to the client and the container does not keep track of it at all any longer. You can think of Spring.NET's role when talking about a non-singleton / prototype object as a replacement for the 'new' operator. Any lifecycle aspects past that point have to be handled by the client. The lifecycle of an object in the
IObjectFactory
is further described in
Section 4.5.1, “Lifecycle interfaces” |
In the XML fragment below, two objects are declared of which one
is defined as a singleton, and the other one as a prototype. The
exampleObject object is created each and every time a
client asks the IObjectFactory for this object,
whereas the yetAnotherExample object is only created
once; a reference to the exact same instance is returned on each request
for this object.
<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary" singleton="false"/> <object name="yetAnotherExample" type="Examples.ExampleObjectTwo, ExamplesLibrary" singleton="true"/>
The lazy-init attribute gives you control over
when the singleton is instantiated. A common variation on the singleton
design pattern is to lazily create the object, that is to create it only
when it is first used. By default, the lazy-init
attribute is set to false instructing the IoC container to
pre-instantiate singletons object when the container is initialized.
Setting the attribute to false will delay the creation until the object
is first requested from the container, either directly from a user
request or as a result of the resolving object dependencies.
Inversion of Control has already been referred to as
Dependency Injection. The basic principle is that
objects define their dependencies (i.e. the other objects they work
with) only through constructor arguments, arguments to a factory method,
or properties which are set on the object instance after it has been
constructed or returned from a factory method. Then, it is the job of
the container to actually inject those dependencies
when it creates the object. This is fundamentally the inverse (hence the
name Inversion of Control) of the object instantiating or locating its
dependencies on its own using direct construction of classes (via the
new operator), or something like the
Service Locator pattern. While we will not
elaborate too much on the advantages of Dependency Injection, it becomes
evident upon usage that code gets much cleaner and reaching a higher
grade of decoupling is much easier when objects do not look up their
dependencies, but are provided them, and additionally do not even know
where the dependencies are located and of what actual type they
are.
As touched on in the previous paragraph, Inversion of Control / Dependency Injection exists in two major variants:
setter-based dependency injection is realized by calling property setters on your objects after invoking a no-argument constructor to instantiate your object. Spring.NET generally advocates the usage of setter-based dependency injection, since a large number of constructor arguments can get unwieldy, especially when some properties are optional.
constructor-based dependency injection is realized by invoking a constructor with a number of arguments, each representing a collaborator or property. Although Spring.NET generally advocates the usage of setter-based dependency injection as much as possible, it does fully support the constructor-based approach as well, since you may wish to use it with pre-existing objects which provide only multi-argument constructors, and no setters. Additionally, for simpler objects, some people prefer the constructor approach as a means of ensuring objects can not be constructed in an invalid state.
The IObjectFactory supports both of these
variants for injecting dependencies into objects it manages. The
configuration for the dependencies comes in the form of the
IObjectDefinition class, which is used together
with TypeConverters to know how to convert properties
from one format to another. However, most users of Spring.NET will not
be dealing with these classes directly (i.e. programmatically), but
rather with an XML definition file which will be converted internally
into instances of these classes, and used to load an entire
IObjectFactory or
IApplicationContext.
Object dependency resolution generally happens as follows:
The IObjectFactory is created and
initialized with a configuration which describes all the objects.
Most Spring.NET users use an IObjectFactory
or IApplicationContext variant that
supports XML format configuration files.
Each object has dependencies expressed in the form of properties or constructor arguments. These will be provided to the object, when the object is actually created.
Each property or constructor-arg is either an actual
definition of the value to set, or a reference to another object
in the IObjectFactory. In the case of the
IApplicationContext, the reference can be
to an object in a parent
IApplicationContext.
Each property or
constructor argument which is a value must be able to be converted
from whatever format it was specified in, to the actual
System.Type of that property or constructor
argument. By default Spring.NET can convert a value supplied in
string format to all built-in types, such as
int, long,
string, bool, etc.
Additionally, when talking about the XML based
IObjectFactory variants (including the
IApplicationContext variants), these have
built-in support for defining IList,
IDictionary, and Set
collection types. Spring.NET uses
TypeConverter definitions to be able to
convert string values to other, arbitrary types. Refer to Section 5.3, “Type conversion” for more information
regarding type conversion, and how you can design your classes to
be convertible by Spring.NET.
It is important to realize that Spring.NET validates the
configuration of each object in the
IObjectFactory when the
IObjectFactory is created, including the
validation that properties that are object references are actually
referring to valid objects (i.e. the objects being referred to are
also defined in the IObjectFactory, or in a
parent context in the case of
IApplicationContext). However, the object
properties themselves are not set until the object is
actually created. For objects that have been defined as
singletons and set to be pre-instantiated (such as singleton
objects in an IApplicationContext),
creation happens at the time that the
IObjectFactory is created, but otherwise
this is only when the object is requested. When an object actually
has to be created, this will potentially cause a graph of other
objects to be created, as its dependencies and its dependencies'
dependencies (and so on) are created and assigned.
You can generally trust Spring.NET to do the right thing. It
will pick up configuration issues, including references to
non-existent object definitions and circular dependencies, at
IObjectFactory load-time. It will actually
set properties and resolve dependencies (i.e. create any dependent
objects if needed) as late as possible, which is when the object
is actually created. This does mean that an
IObjectFactory which has loaded correctly
can later generate an exception when you request an object, if
there is a problem creating that object or one of its
dependencies. This could happen if the object throws an exception
as a result of a missing or invalid property, for example. This
potentially delayed visibility of some configuration issues is why
IApplicationContext by default
pre-instantiates singleton objects. At the cost of some upfront
time and memory to create these objects before they are actually
needed, you find out about configuration issues when the
IApplicationContext is created, not later.
If you wish, you can still override this default behavior and set
any of these singleton objects to lazy-load (not be
preinstantiated).
Some examples (using XML based object definitions)...
First, an example of using the
IObjectFactory for setter-based dependency
injection. Below is a small part of an XML file specifying some object
definitions. Following is the code for the actual main object itself,
showing the appropriate setters declared.
<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary">
<property name="objectOne" ref="anotherExampleObject"/>
<property name="objectTwo" ref="yetAnotherObject"/>
<property name="IntegerProperty" value="1"/>
</object>
<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>
[C#]
public class ExampleObject
{
private AnotherObject objectOne;
private YetAnotherObject objectTwo;
private int i;
public AnotherObject ObjectOne
{
set { this.objectOne = value; }
}
public YetAnotherObject ObjectTwo
{
set { this.objectTwo = value; }
}
public int IntegerProperty
{
set { this.i = value; }
}
}Now, an example of using the IObjectFactory
for IoC Type 3 (Constructor Dependency Injection). Below is a snippet
from an XML configuration that specifies constructor arguments and the
actual object code, showing the constructor:
<object id="exampleObject" type="Examples.ExampleObject, ExamplesLibrary">
<constructor-arg name="objectOne" ref="anotherExampleObject"/>
<constructor-arg name="objectTwo" ref="yetAnotherObject"/>
<constructor-arg name="IntegerProperty" value="1"/>
</object>
<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>
[Visual Basic.NET]
Public Class ExampleObject
Private myObjectOne As AnotherObject
Private myObjectTwo As YetAnotherObject
Private i As Integer
Public Sub New (
anotherObject as AnotherObject,
yetAnotherObject as YetAnotherObject,
i as Integer)
myObjectOne = anotherObject
myObjectTwo = yetAnotherObject
Me.i = i
End Sub
End Class As you can see, the constructor arguments specified
in the object definition will be used to pass in as arguments to the
constructor of the ExampleObject.
Note that Type 2 Setter Injection and Type 3 Constructor Injection IoC are not mutually exclusive... it is perfectly reasonable to use both for a single object definition, as can be seen in the following example:
<object id="exampleObject" type="Examples.MixedIocObject, ExamplesLibrary">
<constructor-arg name="objectOne" ref="anotherExampleObject"/>
<property name="objectTwo" ref="yetAnotherObject"/>
<property name="IntegerProperty" value="1"/>
</object>
<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>
[C#]
public class MixedIocObject
{
private AnotherObject objectOne;
private YetAnotherObject objectTwo;
private int i;
public MixedIocObject (AnotherObject obj)
{
this.objectOne = obj;
}
public YetAnotherObject ObjectTwo
{
set { this.objectTwo = value; }
}
public int IntegerProperty
{
set { this.i = value; }
}
}Now consider a variant of this where instead of using a constructor, Spring is told to call a static factory method to return an instance of the object
<object id="exampleObject" type="Examples.ExampleFactoryMethodObject, ExamplesLibrary"
factory-method="CreateInstance">
<constructor-arg name="objectOne" ref="anotherExampleObject"/>
<constructor-arg name="objectTwo" ref="yetAnotherObject"/>
<constructor-arg name="intProp" value="1"/>
</object>
<object id="anotherExampleObject" type="Examples.AnotherObject, ExamplesLibrary"/>
<object id="yetAnotherObject" type="Examples.YetAnotherObject, ExamplesLibrary"/>
[C#]
public class ExampleFactoryMethodObject
{
private AnotherObject objectOne;
private YetAnotherObject objectTwo;
private int i;
// a private constructor
private ExampleFactoryMethodObject()
{
}
public static ExampleFactoryMethodObject CreateInstance(AnotherObject objectOne,
YetAnotherObject objectTwo,
int intProp)
{
ExampleFactoryMethodObject fmo = new ExampleFactoryMethodObject();
fmo.AnotherObject = objectOne;
fmo.YetAnotherObject = objectTwo;
fmo.IntegerProperty = intProp;
return fmo;
}
// Property definitions
}Note that arguments to the static factory method are supplied via constructor-arg elements, exactly the same as if a constructor had actually been used. These arguments are optional. Also, it is important to realize that the type of the class being returned by the factory method does not have to be of the same type as the class which contains the static factory method, although in this example it is. An instance (non-static) factory method, mentioned previously, would be used in an essentially identical fashion (aside from the use of the factory-object attribute instead of the type attribute), so will not be detailed here.
Constructor argument resolution matching occurs using the
argument's type. When another object is referenced, the type is known,
and matching can occur. When a simple type is used, such as
<value>1</value>, Spring.NET cannot
determine the type of the value, and so cannot match by type without
help. Consider the following class, which is used for the following two
sections:
using System;
namespace SimpleApp
{
public class ExampleObject
{
private int years; //No. of years to the calculate the Ultimate Answer
private string ultimateAnswer; //The Answer to Life, the Universe, and Everything
public ExampleObject(int years, string ultimateAnswer)
{
this.years = years;
this.ultimateAnswer = ultimateAnswer;
}
public string UltimateAnswer
{
get { return this.ultimateAnswer; }
}
public int Years
{
get { return this.years; }
}
}
}The above scenario can use type matching
with simple types by explicitly specifying the type of the constructor
argument using the type attribute. For example:
<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp"> <constructor-arg type="int" value="7500000"/> <constructor-arg type="string" value="42"/> </object>
The type attribute specifies the System.Type
of the constructor argument, such as System.Int32. Alias' are
available to for common simple types (and their array equivalents).
These alias' are...
Table 4.2. Type aliases
| Type | Alias' | Array Alias' |
|---|---|---|
| System.Char | char, Char | char[], Char() |
| System.Int16 | short, Short | short[], Short() |
| System.Int32 | int, Integer | int[], Integer() |
| System.Int64 | long, Long | long[], Long() |
| System.UInt16 | ushort | ushort[] |
| System.UInt32 | uint | uint[] |
| System.UInt64 | ulong | ulong[] |
| System.Float | float, Single | float[], Single() |
| System.Double | double, Double | double[], Double() |
| System.Date | date, Date | date[], Date() |
| System.Decimal | decimal, Decimal | decimal[], Decimal() |
| System.Bool | bool, Boolean | bool[], Boolean() |
| System.String | string, String | string[], String() |
Constructor arguments can have their index specified explicitly
by use of the index attribute. For example:
<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp"> <constructor-arg index="0" value="7500000"/> <constructor-arg index="1" value="42"/> </object>
As well as solving the ambiguity problem of multiple simple values, specifying an index also solves the problem of ambiguity where a constructor may have two arguments of the same type. Note that the index is 0 based.
Constructor arguments can also be specified by name by using the
name attribute of the
<constructor-arg> element.
<object name="exampleObject" type="SimpleApp.ExampleObject, SimpleApp"> <constructor-arg name="years" value="7500000"/> <constructor-arg name="ultimateAnswer" value="42"/> </object>
As mentioned in the previous section, object properties and
constructor arguments can be defined as either references to other
managed objects (collaborators). The
XmlObjectFactory (located in the
Spring.Objects.Factory.Xml namespace) supports a
number of sub-element types within its property and
constructor-arg elements for this purpose.
The value element specifies a property or
constructor argument as a human-readable string representation. As
mentioned in detail previously,
TypeConverter instances are used to convert these
string values from a System.String to the actual
property or argument type. Custom TypeConverter
implementations in the Spring.Objects.TypeConverters
namespace are used to augment the functionality offered by the .NET
BCL's default TypeConverter
implementations.
In the following example, we use a
SqlConnection from the
System.Data.SqlClient namespace of the BCL. This
class (like many other existing classes) can easily be used in a
Spring.NET object factory, as it offers a convenient public property for
configuration of its ConnectionString property.
<objects xmlns="http://www.springframework.net">
<object id="myConnection" type="System.Data.SqlClient.SqlConnection">
<!-- results in a call to the setter of the ConnectionString property -->
<property
name="ConnectionString"
value="Integrated Security=SSPI;database=northwind;server=mySQLServer"/>
</object>
</objects>The <null> element is used to handle
null values. Spring.NET treats empty arguments for
properties and constructor arguments as empty
string instances. The following configuration
demonstrates this behaviour...
<object type="Examples.ExampleObject,
ExamplesLibrary"> <property
name="email"><value></value></property>
<!-- equivalent, using value attribute as opposed to nested
<value/> element... <property name="email"
value=""/> </object>This results in the email property being set to the empty string
value (""), in much the same way as can be seen in
the following snippet of C# code...
exampleObject.Email = "";
The special <null/> element may be used to
indicate a null value; to wit...
<object type="Examples.ExampleObject,
ExamplesLibrary"> <property
name="email"><null/></property>
</object>This results in the email property being set to
null, again in much the same way as can be seen in
the following snippet of C# code...
exampleObject.Email = null;
The list, set,
name-values and dictionary
elements allow properties and arguments of the type
IList, ISet,
NameValueCollection and
IDictionary, respectively, to be defined and set.
<objects xmlns="http://www.springframework.net">
<object id="moreComplexObject" type="Example.ComplexObject">
<!--
results in a call to the setter of the SomeList (System.Collections.IList) property
-->
<property name="SomeList">
<list>
<value>a list element followed by a reference</value>
<ref object="myConnection"/>
</list>
</property>
<!--
results in a call to the setter of the SomeDictionary (System.Collections.IDictionary) property
-->
<property name="SomeDictionary">
<dictionary>
<entry key="a string => string entry" value="just some string"/>
<entry key-ref="myKeyObject" value-ref="myConnection"/>
</dictionary>
</property>
<!--
results in a call to the setter of the SomeNameValue (System.Collections.NameValueCollection) property
-->
<property name="SomeNameValue">
<name-values>
<add key="HarryPotter" value="The magic property"/>
<add key="JerrySeinfeld" value="The funny (to Americans) property"/>
</name-values>
</property>
<!--
results in a call to the setter of the SomeSet (Spring.Collections.ISet) property
-->
<property name="someSet">
<set>
<value>just some string</value>
<ref object="myConnection"/>
</set>
</property>
</object>
</objects>Many classes in the BCL expose only read-only properties for collection classes. When Spring.NET encounters a read-only collection, it will configure the collection by using the getter property to obtain a reference to the collection class and then proceed to add the additional elements to the existing collection. This results in an additive behavior for collection properties that are exposed in this manner.
Note that the value of a Dictionary entry, or a set value, can also again be any of the elements:
(object | ref | idref | list | set | dictionary |
name-values | value | null)
The shortcut forms for value and references are useful to reduce XML verbosity when setting collection properties. See Section 4.3.3.8, “Value and ref shortcut forms” for more information.
Please be advised that the setting of multiple values for a
NameValueCollection is planned
for a future release.
Spring supports setting values for classes that expose
properties based on the generic collection interfaces
IList<T> and
IDictionary<TKey, TValue>. The type
parameter for these collections is specified by using the XML
attribute element-type for
IList<T> and the XML attributes
key-type and value-type for
IDictionary<TKey, TValue>. The values of
the collection are automaticaly converted from a string to the
appropriate type. If you are using your own user-defined type as a
generic type parameter you will likely need to register a custom type
converter. Refer to Section 4.4, “Type conversion” for
more information. The implementations of
IList<T> and
IDictionary<TKey, TValue> that is created
are System.Collections.Generic.List and
System.Collections.Generic.Dictionary.
The following class represents a lottery ticket and demonstrates how to set the values of a generic IList.
public class LotteryTicket { List<int> list;
DateTime date; public List<int> Numbers { set { list = value; }
get { return list; } } public DateTime Date { get { return date; } set {
date = value; } } }The XML fragment that can be used to configure this class is shown below
<object
id="MyLotteryTicket"
type="GenericsPlay.Lottery.LotteryTicket, GenericsPlay">
<property name="Numbers"> <list
element-type="int"> <value>11</value>
<value>21</value> <value>23</value>
<value>34</value> <value>36</value>
<value>38</value> </list> </property>
<property name="Date" value="4/16/2006"/>
</object>The following shows the definition of a more complex class that
demonstrates the use of generics using the
Spring.Expressions.IExpression interface as the
generic type parameter for the IList element-type and the value-type
for IDictionary. Spring.Expressions.IExpression
has an associated type converter,
Spring.Objects.TypeConverters.ExpressionConverter
that is already pre-registered with Spring.
public class GenericExpressionHolder { private
System.Collections.Generic.IList<IExpression> expressionsList;
private System.Collections.Generic.IDictionary<string,
IExpression> expressionsDictionary; public
System.Collections.Generic.IList<IExpression> ExpressionsList {
set { this.expressionsList = value; } } public
System.Collections.Generic.IDictionary<string,IExpression>
ExpressionsDictionary { set { this.expressionsDictionary = value; } }
public IExpression this[int index] { get { return
this.expressionsList[index]; } } public IExpression this[string key] {
get { return this.expressionsDictionary[key]; } } }An example XML configuration of this class is shown below
<object id="genericExpressionHolder"
type="Spring.Objects.Factory.Xml.GenericExpressionHolder,
Spring.Core.Tests"> <property
name="ExpressionsList"> <list
element-type="Spring.Expressions.IExpression, Spring.Core">
<value>1 + 1</value>
<value>date('1856-7-9').Month</value>
<value>'Nikola Tesla'.ToUpper()</value>
<value>DateTime.Today >
date('1856-7-9')</value> </list>
</property> <property
name="ExpressionsDictionary"> <dictionary
key-type="string"
value-type="Spring.Expressions.IExpression, Spring.Core">
<entry key="zero"> <value>1 + 1</value>
</entry> <entry key="one">
<value>date('1856-7-9').Month</value>
</entry> <entry key="two">
<value>'Nikola Tesla'.ToUpper()</value>
</entry> <entry key="three">
<value>DateTime.Today >
date('1856-7-9')</value> </entry>
</dictionary> </property> </object>An indexer lets you set and get values from a collection using a
familiar bracket [] notation. Spring's XML
configuration supports the setting of indexer properties. Overloaded
indexers as well as multiparameter indexers are also supported. The
property expression parser described in Chapter 10, Expression Evaluation
is used to perform the type conversion of the indexer name argument
from a string in the XML file to a matching target type. As an example
consider the following class
public class Person { private IList
favoriteNames = new ArrayList(); private IDictionary properties = new
Hashtable(); public Person() { favoriteNames.Add("p1");
favoriteNames.Add("p2"); } public string this[int index] { get {
return (string)favoriteNames[index]; } set { favoriteNames[index] =
value; } } public string this[string keyName] { get { return (string)
properties[keyName]; } set { properties.Add(keyName,value); } } }The XML configuration snippit to populate this object with data is shown below
<object id="person"
type="Test.Objects.Person, Test.Objects"> <property
name="[0]" value="Master Shake"/> <property
name="['one']" value="uno"/>
</object> | Note |
|---|---|
| The use of the property expression parser in Release 1.0.2
changed how you configure indexer properties. The following section
describes this usage. The older style configuration uses the following syntax <object id="objectWithIndexer"
type="Spring.Objects.TestObject, Spring.Core.Tests">
<property name="Item[0]" value="my string
value"/> </object> You can also change the
name used to identify the indexer by adorning your indexer method
declaration with the attribute
There are some limitations to be aware in the older indexer configuration. The indexer can only be of a single parameter that is convertable from a string to the indexer parameter type. Also, multiple indexers are not supported. You can get around that last limitation currently if you use the IndexerName attribute. |
An object element inside the
property element is used to define an object value
inline, instead of referring to an object defined elsewhere in the
container. The inline object definition does not need to have any id
or name defined (indeed, if any are defined, they will be ignored).
<object id="outer" type="...">
<!-- Instead of using a reference to target, just use an inner
object --> <property name="target"> <object
type="ExampleApp.Person, ExampleApp"> <property
name="name" value="Tony"/> <property
name="age" value="51"/> </object>
</property> </object>An idref element is simply a shorthand and error-proof way to set a property to the String id or name of another object in the container.
<object
id="theTargetObject" type="..."> </object>
<object id="theClientObject" type="...">
<property name="targetName"> <idref
object="theTargetObject"/> </property>
</object>This is exactly equivalent at runtime to the following fragment:
<object
id="theTargetObject" type="..."> </object>
<object id="theClientObject" type="...">
<property name="targetName"
value="theTargetObject"/> </object>The main
reason the first form is preferable to the second is that using the
idref tag will allow Spring.NET to validate at
deployment time that the other object actually exists. In the second
variation, the class that is having its
targetName property injected is forced to do its
own validation, and that will only happen when that class is actually
instantiated by the container, possibly long after the container is
actually up and running.
Additionally, if the object being referred to is in the same
actual XML file, and the object name is the object
id, the local attribute may be
used, which will allow the XML parser itself to validate the object
name even earlier, at parse time.
<property name="targetName">
<idref local="theTargetObject"/> </property>The ref element is the final element allowed
inside a property definition element. It is used to
set the value of the specified property to be a reference to another
object managed by the container, a collaborator, so to speak. As you
saw in the previous example to set collection properties, we used the
SqlConnection instance from the initial example
as a collaborator and specified it using a <ref object/>
element. As mentioned in a previous section, the referred-to object is
considered to be a dependency of the object who's property is being
set, and will be initialized on demand as needed (if it is a singleton
object it may have already been initialized by the container) before
the property is set. All references are ultimately just a reference to
another object, but there are 3 variations on how the id/name of the
other object may be specified, which determines how scoping and
validation is handled.
Specifying the target object by using the
object attribute of the ref tag
is the most general form, and will allow creating a reference to any
object in the same IObjectFactory /
IApplicationContext (whether or not in the same
XML file), or parent IObjectFactory /
IApplicationContext. The value of the
object attribute may be the same as either the
id attribute of the target object, or one of the
values in the name attribute of the target
object.
<ref
object="someObject"/>Specifying the target object by using the
local attribute leverages the ability of the XML
parser to validate XML id references within the same file. The value
of the local attribute must be the same as the
id attribute of the target object. The XML parser
will issue an error if no matching element is found in the same file.
As such, using the local variant is the best choice (in order to know
about errors are early as possible) if the target object is in the
same XML file.
<ref
local="someObject"/>Specifying the target object by using the
parent attribute allows a reference to be created
to an object that is in a parent IObjectFactory
(orIApplicationContext) of the current
IObjectFactory (or
IApplicationContext). The value of the
parent attribute may be the same as either the
id attribute of the target object, or one of the
values in the name attribute of the target object,
and the target object must be in a
parent IObjectFactory or
IApplicationContext of the current one. The
main use of this object reference variant is when there is a need to
wrap an existing object in a parent context with some sort of proxy
(which may have the same name as the parent), and needs the original
object so it may wrap it.
<ref parent="someObject"/>
There are also some shortcut forms that are less verbose than
using the full value and ref
elements. The property,
constructor-arg, and entry
elements all support a value attribute which may be
used instead of embedding a full value element.
Therefore, the following:
<property name="myProperty">
<value>hello</value> </property>
<constructor-arg> <value>hello</value>
</constructor-arg> <entry key="myKey">
<value>hello</value> </entry>are equivalent to:
<property
name="myProperty" value="hello"/>
<constructor-arg value="hello"/> <entry
key="myKey" value="hello"/>In general, when typing definitions by hand, you will probably prefer to use the less verbose shortcut form.
The property and
constructor-arg elements support a similar shortcut
ref attribute which may be used instead of a full
nested ref element. Therefore, the following...
<property name="myProperty"> <ref
object="anotherObject"/> </property>
<constructor-arg index="0"> <ref
object="anotherObject"/> </constructor-arg>is equivalent to...
<property
name="myProperty" ref="anotherObject"/>
<constructor-arg index="0" ref="anotherObject"/> | Note |
|---|---|
The shortcut form is equivalent to a <ref
object="xxx"> element; there is no shortcut for either
the <ref local="xxx"> or <ref
parent="xxx"> elements. For a local or parent
ref, you must still use the long form. |
Finally, the entry element allows a shortcut form the specify the key and/or value of a dictionary, in the form of key/key-ref and value/value-ref attributes. Therefore, the following
<entry> <key><ref
object="MyKeyObject"/></key> <ref
object="MyValueObject"/> </entry>Is equivalent to:
<entry
key-ref="MyKeyObject" value-ref="MyValueObject"/> As
mentioned previously, the equivalence is to <ref
object="xxx"> and not the local or parent forms of object
references.
Note that compound or nested property names are perfectly legal when setting object properties, as long as all components of the path except the final property name are non-null. For example, in this object definition:
<object id="foo" type="Spring.Foo,
Spring.Foo"> <property name="bar.baz.name"
value="Bingo"/> </object>For most users, the majority of the objects in the container will be singletons. When a singleton object needs to collaborate with (use) another singleton object, or a non-singleton object needs to collaborate with another non-singleton object, the typical and common approach of handling this dependency (by defining one object to be a property of the other) is quite adequate. There is however a problem when the object lifecycles are different. Consider a singleton object A which needs to use a non-singleton (prototype) object B, perhaps on each method invocation on A. The container will only create the singleton object A once, and thus only get the opportunity to set its properties once. There is no opportunity for the container to provide object A with a new instance of object B every time one is needed.
One solution to this problem is to forego some inversion of
control. Object A can be aware of the container by implementing the
IObjectFactoryAware interface, and use
programmatic means to ask the container via a
GetObject("B") call for (a new) object B every time
it needs it. This is generally not a desirable solution since the object
code is then aware of and coupled to Spring.NET.
Method Injection, an advanced feature of supporting
IObjectFactoryAware implementations, allows this
use case to be handled in a clean fashion, along with some other
scenarios.
Lookup method injection refers to the ability of the container
to override abstract or concrete methods on managed
objects in the container, and to return the result of looking up
another named object in the container. The lookup will typically be of
a non-singleton object as per the scenario described above (although
it can also be a singleton). Spring.NET implements this through a
dynamically generated subclass overriding the method using the classes
in the System.Reflection.Emit namespace.
In the client class containing the method to be injected, the method definition must observe the following form:
protected abstract SingleShotHelper CreateSingleShotHelper();
If the method is not abstract, Spring.NET
will simply override the existing implementation. In the
XmlObjectFactory case, you instruct Spring.NET
to inject / override this method to return a particular object from
the container, by using the lookup-method element
inside the object definition. For example:
<!-- a stateful object deployed as a prototype (non-singleton) -->
<object id="singleShotHelper" class="..." singleton="false"/>
<!-- myobject uses singleShotHelper -->
<object id="myObject" type="...">
<lookup-method name="CreateSingleShotHelper" object="singleShotHelper"/>
<property>
...
</property>
</object>The object identified as myObject will call
its own method CreateSingleShotHelper whenever it
needs a new instance of the singleShotHelper
object. It is important to note that the person deploying the objects
must be careful to deploy the singleShotHelper
object as a non-singleton (if that is actually what is needed). If it
is deployed as a singleton (either explicitly, or relying on the
default true setting for this flag), the same
instance of singleShotHelper will be returned each
time!
Note that lookup method injection can be combined with Constructor Injection (supplying optional constructor arguments to the object being constructed), and also with Setter Injection (settings properties on the object being constructed).
A less commonly useful form of method injection than Lookup Method Injection is the ability to replace arbitrary methods in a managed object with another method implementation. Users may safely skip the rest of this section (which describes this somewhat advanced feature), until this functionality is actually needed.
In an XmlObjectFactory, the
replaced-method element may be used to replace an
existing method implementation with another. Consider the following
class, with a method ComputeValue, which we want to
override:
public class MyValueCalculator {
public virtual string ComputeValue(string input) {
// ... some real code
}
// ... some other methods
}A class implementing the
Spring.Objects.Factory.Support.IMethodReplacer
interface is needed to provide the new (injected) method
definition.
/// <summary>
/// Meant to be used to override the existing ComputeValue(string)
/// implementation in MyValueCalculator.
/// </summary>
public class ReplacementComputeValue : IMethodReplacer
{
public object Implement(object target, MethodInfo method, object[] arguments)
{
// get the input value, work with it, and return a computed result...
string value = (string) arguments[0];
// compute...
return result;
}
}The attendant IObjectFactory definition
to deploy the original class and specify the method override would
look like:
<object id="myValueCalculator" type="Examples.MyValueCalculator, ExampleAssembly">
<!-- arbitrary method replacement -->
<replaced-method name="ComputeValue" replacer="replacementComputeValue">
<arg-type match="String"/>
</replaced-method>
</object>
<object id="replacementComputeValue" type="Examples.ReplaceMentComputeValue, ExampleAssembly"/>One or more contained arg-type elements
within the replaced-method element may be used to
indicate the method signature of the method being overridden. Note
that the signature for the arguments is actually only needed in the
case that the method is actually overloaded and there are multiple
variants within the class. For convenience, the type string for an
argument may be a substring of the fully qualified type name. For
example, all the following would match
System.String.
System.String
String
StrSince the number of arguments is often enough to distinguish between each possible choice, this shortcut can save a lot of typing, by just using the shortest string which will match an argument.
This section details those configuration scenarios that involve
the setting of properties and constructor arguments using the members of
other objects and classes. This kind of scenario is quite common,
especially when dealing with legacy classes that you cannot (or won't)
change to accommodate some of Spring.NET's conventions... consider the
case of a class that has a contructor argument that can only be
calculated by going to say, a database. The
MethodInvokingFactoryObject handles exactly this
scenario ... it will allow you to inject the result of an arbitrary
method invocation into a constructor (as an argument) or as the value of
a property setter. Similary,
PropertyRetrievingFactoryObject and
FieldRetrievingFactoryObject allow you to
retrieve values from another objects property or field value. These
classes implement the IFactoryObject interface
which indicates to Spring.NET that this object is itself a factory and
the factories product, not the factory itself, is what will be
associated with the object id. Factory objects are discussed futher in
Section 4.5.3, “IFactoryObject”
The PropertyRetrievingFactoryObject is an
IFactoryObject that addresses the scenario of
setting one of the properties and / or constructor arguments of an
object to the value of a property exposed on another object or class.
One can use it to get the value of any public property exposed on either an instance
or a class (in the case of a property exposed on a class, the property
must obviously be static).
In the case of a property exposed on an instance, the target
object that a PropertyRetrievingFactoryObject
will evaluate can be either an object instance specified directly
inline or a reference to another arbitrary object. In the case of a
static property exposed on a class, the target object will be the
class (the .NET System.Type) exposing the
property.
The result of evaluating the property lookup may then be used in
another object definition as a property value or constructor argument.
Note that nested properties are supported for both instance and class
property lookups. The IFactoryObject is
discussed more generally in Section 4.5.3, “IFactoryObject”.
Here's an example where a property path is used against another object instance. In this case, an inner object definition is used and the property path is nested, i.e. spouse.age.
<object name="person" type="Spring.Objects.TestObject, Spring.Core.Tests">
<property name="age" value="20"/>
<property name="spouse">
<object type="Spring.Objects.TestObject, Spring.Core.Tests">
<property name="age" value="21"/>
</object>
</property>
</object>
// will result in 21, which is the value of property 'spouse.age' of object 'person'
<object name="theAge" type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
<property name="TargetObject" ref="person"/>
<property name="TargetProperty" value="spouse.age"/>
</object>An example of using a
PropertyRetrievingFactoryObject to evaluate a
static property is shown below.
<object id="cultureAware"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
<property name="culture" ref="cultureFactory"/>
</object>
<object id="cultureFactory"
type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
<property name="StaticProperty">
<value>System.Globalization.CultureInfo.CurrentUICulture, Mscorlib</value>
</property>
</object>Similarly, an example showing the use of an instance property is shown below.
<object id="instancePropertyCultureAware"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
<property name="Culture" ref="instancePropertyCultureFactory"/>
</object>
<object id="instancePropertyCultureFactory"
type="Spring.Objects.Factory.Config.PropertyRetrievingFactoryObject, Spring.Core">
<property name="TargetObject" ref="instancePropertyCultureAwareSource"/>
<property name="TargetProperty" value="MyDefaultCulture"/>
</object>
<object id="instancePropertyCultureAwareSource"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests"/>
The FieldRetrievingFactoryObject class
addresses much the same area of concern as the
PropertyRetrievingFactoryObject described in
the previous section. However, as its name might suggest, the
FieldRetrievingFactoryObject class is concerned
with looking up the value of a public
field exposed on either an instance or a class (and similarly, in the
case of a field exposed on a class, the field must obviously be
static).
The following example demonstrates using a
FieldRetrievingFactoryObject to look up the
value of a (public, static) field exposed on a class
<object id="withTypesField"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
<property name="Types" ref="emptyTypesFactory"/>
</object>
<object id="emptyTypesFactory"
type="Spring.Objects.Factory.Config.FieldRetrievingFactoryObject, Spring.Core">
<property name="TargetType" value="System.Type, Mscorlib"/>
<property name="TargetField" value="EmPTytypeS"/>
</object>
The example in the next section demonstrates the look up of a (public) field exposed on an object instance.
<object id="instanceCultureAware"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests">
<property name="Culture" ref="instanceCultureFactory"/>
</object>
<object id="instanceCultureFactory"
type="Spring.Objects.Factory.Config.FieldRetrievingFactoryObject, Spring.Core">
<property name="TargetObject" ref="instanceCultureAwareSource"/>
<property name="TargetField" value="Default"/>
</object>
<object id="instanceCultureAwareSource"
type="Spring.Objects.Factory.Xml.XmlObjectFactoryTests+MyTestObject, Spring.Core.Tests"/>
The MethodInvokingFactoryObject rounds
out the trio of classes that permit the setting of properties and
constructor arguments using the members of other objects and classes.
Whereas the PropertyRetrievingFactoryObject and
FieldRetrievingFactoryObject classes dealt with
simply looking looking up and returning the value of property or field
on an object or class, the
MethodInvokingFactoryObject allows one to set a
constructor or property to the return value of an arbitrary method
invocation,
The MethodInvokingFactoryObject class
handles both the case of invoking an (instance) method on another
object in the container, and the case of a static method call on an
arbitrary class. Additonally, it is sometimes neccessary to invoke a
method just to perform some sort of initialization.... while the
mechanisms for handling object initialization have yet to be
introduced (see Section 4.5.1.1, “IInitializingObject / init-method”), these
mechanisms do not permit any arguments to be passed to any
initialization method, and are confined to invoking an initialization
method on the object that has just been instantiated by the container.
The MethodInvokingFactoryObject allows one to
invoke pretty much any method on any
object (or class in the case of a static method).
The following example (in an XML based
IObjectFactory definition) uses the
MethodInvokingFactoryObject class to force a
call to a static factory method prior to the instantiation of the
object...
<object id="force-init"
type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
<property name="StaticMethod">
<value>ExampleNamespace.ExampleInitializerClass.Initialize</value>
</property>
</object>
<object id="myService" depends-on="force-init"/> Note
that the definition for the myService object has
used the depends-on attribute to refer to the
force-init object, which will force the
initialization of the force-init object first (and
thus the calling of its configured StaticMethod
static initializer method, when myService is first
initialized. Please note that in order to effect this initialization,
the MethodInvokingFactoryObject object
must be operating in
singleton mode (the default.. see the next
paragraph).
Note that since this class is expected to be used primarily for
accessing factory methods, this factory defaults to operating in
singleton mode. As such, as soon as all of the
properties for a MethodInvokingFactoryObject
object have been set, and if the
MethodInvokingFactoryObject object is still in
singleton mode, the method will be invoked
immediately and the return value cached for later access. The first
request by the container for the factory to produce an object will
cause the factory to return the cached return value for the current
request (and all subsequent requests). The
IsSingleton property may be set to false, to
cause this factory to invoke the target method each time it is asked
for an object (in this case there is obviously no caching of the
return value).
A static target method may be specified by setting the
targetMethod property to a string
representing the static method name, with
TargetType specifying the
Type that the static method is defined on.
Alternatively, a target instance method may be specified, by setting
the TargetObject property to the name of
another Spring.NET managed object definition (the target object), and
the TargetMethod property to the name of the
method to call on that target object.
Arguments for the method invocation may be specified in two ways
(or even a mixture of both)... the first involves setting the
Arguments property to the list of arguments
for the method that is to be invoked. Note that the ordering of these
arguments is significant... the order of the values passed to the
Arguments property must be the same as the
order of the arguments defined on the method signature, including the
argumentType. This is shown in the example
below
<object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
<property name="TargetType" value="Whatever.MyClassFactory, MyAssembly"/>
<property name="TargetMethod" value="GetInstance"/>
<!-- the ordering of arguments is significant -->
<property name="Arguments">
<list>
<value>1st</value>
<value>2nd</value>
<value>and 3rd arguments</value>
<!-- automatic Type-conversion will be performed prior to invoking the method -->
</list>
</property>
</object>The second way involves passing an arguments dictionary to the
NamedArguments property... this dictionary
maps argument names (Strings) to argument
values (any object). The argument names are not case-sensitive, and
order is (obviously) not significant (since dictionaries by definition
do not have an order). This is shown in the example below
<object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
<property name="TargetObject">
<object type="Whatever.MyClassFactory, MyAssembly"/>
</property>
<property name="TargetMethod" value="Execute"/>
<!-- the ordering of named arguments is not significant -->
<property name="NamedArguments">
<dictionary>
<entry key="argumentName"><value>1st</value></entry>
<entry key="finalArgumentName"><value>and 3rd arguments</value></entry>
<entry key="anotherArgumentName"><value>2nd</value></entry>
</dictionary>
</property>
</object>The following example shows how use
MethodInvokingFactoryObject to call an instance
method.
<object id="myMethodObject" type="Whatever.MyClassFactory, MyAssembly" /> <object id="myObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core"> <property name="TargetObject" ref="myMethodObject"/> <property name="TargetMethod" value="Execute"/> </object>
The above example could also have been written using an anonymous inner object definition... if the object on which the method is to be invoked is not going to be used outside of the factory object definition, then this is the preferred idiom because it limits the scope of the object on which the method is to be invoked to the surrounding factory object.
Finally, if you want to use
MethodInvokingFactoryObject in conjunction with
a method that has a variable length argument list, then please note
that the variable arguments need to be passed (and configured) as a
list. Let us consider the following method
definition that uses the params keyword (in
C#), and its attendant (XML) configuration...
[C#]
public class MyClassFactory
{
public object CreateObject(Type objectType, params string[] arguments)
{
return ... // implementation elided for clarity...
}
}
<object id="myMethodObject" type="Whatever.MyClassFactory, MyAssembly" />
<object id="paramsMethodObject" type="Spring.Objects.Factory.Config.MethodInvokingFactoryObject, Spring.Core">
<property name="TargetObject" ref="myMethodObject"/>
<property name="TargetMethod" value="CreateObject"/>
<property name="Arguments">
<list>
<value>System.String</value>
<!-- here is the 'params string[] arguments' -->
<list>
<value>1st</value>
<value>2nd</value>
</list>
</list>
</object>In addition to
PropertyRetrievingFactoryObject,
MethodInvokingFactoryObject, and
FieldRetrievingFactoryObject Spring.NET comes
with other useful implementations of the
IFactoryObject interface. These are discussed
below.
The Log4NetFactoryObject is useful when
you would like to share a logging instance across a number of classes
instead of creating a logging instance per class or class hierarchy.
In the example shown below the same logging instance, with a log4Net
name of "DAOLogger", is used in both the SimpleAccountDao and
SimpleProducDao data access objects.
<objects xmlns="http://www.springframework.net"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.net
http://www.springframework.net/xsd/spring-objects.xsd" >
<object name="daoLogger" type="Spring.Objects.Factory.Config.Log4NetFactoryObject, Spring.Core">
<property name="logName" value="DAOLogger"/>
</object>
<object name="productDao" type="PropPlayApp.SimpleProductDao, PropPlayApp ">
<property name="maxResults" value="100"/>
<property name="dbConnection" ref="myConnection"/>
<property name="log" ref="daoLogger"/>
</object>
<object name="accountDao" type="PropPlayApp.SimpleAccountDao, PropPlayApp ">
<property name="maxResults" value="100"/>
<property name="dbConnection" ref="myConnection"/>
<property name="log" ref="daoLogger"/>
</object>
<object name="myConnection" type="System.Data.Odbc.OdbcConnection, System.Data">
<property name="connectionstring" value="dsn=MyDSN;uid=sa;pwd=myPassword;"/>
</object>
</objects>Spring.NET uses the <ref/> element to
express references to other dependant objects. Unless you have some
special initialization requirements, you don't have to use the
<depends-on/> element. However, when you are
using statics that need initialization or some object needs to be
initialized because of something else needing preparation, you can use
the <depends-on/> element. This will ensure all
objects you've listed as dependencies will get initialized before
they're actually set on the object. For example...
<object id="objectOne" type="Examples.ExampleObject, ExamplesLibrary" depends-on="manager"> <property name="manager" ref="manager"/> </object> <object id="manager" type="ManagerObject"/>
Spring.NET has autowire capabilities, meaning that it is possible to automatically let Spring.NET resolve collaborators (other objects) for your object by inspecting the object definitions in the container. Autowiring is specified per object and can thus be enabled for some objects, while other objects won't be autowired. Using autowiring, it is possible to reduce or even wholly eliminate the need to specify properties or constructor arguments. [2] The autowiring functionality has five modes...
Table 4.3. Autowiring modes
| Mode | Explanation |
|---|---|
| no | No autowiring at all. This is the default value and you are encouraged not to change this for large applications, since specifying your collaborators explicitly gives you a feeling for what you're actually doing (always a bonus) and is a great way of somewhat documenting the structure of your system. |
| byName | This option will inspect the objects within the
container, and look for an object named exactly the same as
the property which needs to be autowired. For example, if you
have an object definition that is set to autowire by name, and
it contains a Master property, Spring.NET
will look for an object definition named
Master, and use it as the value of the
Master property on your object
definition. |
| byType | This option gives you the ability to resolve
collaborators by type instead of by name. Supposing you have
an IObjectDefinition with a
collaborator typed SqlConnection,
Spring.NET will search the entire object factory for an object
definition of type SqlConnection and
use it as the collaborator. If 0 (zero) or more than
1 (one) object definitions of the desired type exist in the
container, a failure will be reported and you won't be able to
use autowiring for that specific object. |
| constructor | This is analogous to byType, but applies to constructor arguments. If there isn't exactly one object of the constructor argument type in the object factory, a fatal error is raised. |
| autodetect | Chooses constructor or byType through introspection of the object class. If a default constructor is found, byType gets applied. |
| Note |
|---|---|
| Explicit dependencies always override autowiring. Autowire behavior can be combined with dependency checking, which will be performed after all autowiring has been completed. |
Spring.NET has the ability to try to check for the existence of unresolved dependencies of an object deployed into the container. These are properties of the object, which do not have actual values set for them in the object definition, or alternately provided automatically by the autowiring feature.
This feature is sometimes useful when you want to ensure that all
properties (or all properties of a certain type) are set on an object.
Of course, in many cases an object class will have default values for
many properties, or some properties do not apply to all usage scenarios,
so this feature is of limited use. Dependency checking can also be
enabled and disabled per object, just as with the autowiring
functionality. The default dependency checking mode is to
not check dependencies. Dependency checking can be
handled in several different modes. In XML-based configuration, this is
specified via the dependency-check attribute in an
object definition, which may have the following values.
Table 4.4. Dependency checking modes
| Mode | Explanation |
|---|---|
| none | No dependency checking. Properties of the object which have no value specified for them are simply not set. |
| simple | Dependency checking is done for primitive types and collections (this means everything except collaborators). |
| object | Dependency checking is done for collaborators only. |
| all | Dependency checking is done for collaborators, primitive types and collections. |
Type converters are responsible for converting objects from one type
to another. When using the XML based file to configure the IoC container,
string based property values are converted to the target property type.
Spring will rely on the standard .NET support for type conversion unless
an alternative TypeConverter is registered for a
given type. How to register custom TypeConverters will be described
shortly. As a reminder, the standard .NET type converter support works by
associating a TypeConverter attribute with the
class definition by passing the type of the converter as an attribute
argument. [3] For example, an abbreviated class definition for the BCL
type Font is shown below.
[Serializable, TypeConverter(typeof(FontConverter)), ...]
public sealed class Font : MarshalByRefObject, ICloneable, ISerializable, IDisposable
{
// Methods
... etc ..
}