XMLConfig - Spring Python's native XML format
=============================================
.. highlight:: xml
*XMLConfig* is a class that scans object definitions stored in the XML
format defined for Spring Python. It looks very similar to Spring Java's 2.5
XSD spec, with some small changes.
The following is a simple definition of objects. Later sections will show other
options you have for wiring things together.::
.. highlight:: python
The definitions stored in this file are fed to an *XMLConfig* instance which
scans it, and then sends the meta-data to the *ApplicationContext*. Then, when
the application code requests an object named MovieLister from the container,
the container utilizes an object factory to create the object and return it::
from springpython.context import ApplicationContext
from springpython.config import XMLConfig
container = ApplicationContext(XMLConfig("app-context.xml"))
service = container.get_object("MovieLister")
.. _objects-xmlconfig-referenced-objects:
Referenced Objects
------------------
A referenced object is where an object is needed, but instead of providing the
definition right there, there is, instead, a name, referring to another object
definition.
Object definitions can refer to other objects in many places including:
properties, constructor arguments, and objects embedded inside various
collections. This is the way to break things down into smaller pieces. It
also allows you more efficiently use memory and guarantee different objects
are linked to the same backend object.
.. highlight:: xml
The following fragment, pulled from the earlier example, shows two different
properties referencing other objects. It demonstrates the two ways to refer
to another object::
This means that instead of defining the object meant to be injected into the
*description* property right there, the container must look elsewhere amongst
its collection of object definitions for an object named *SingletonString*.
.. note::
* **Referenced objects don't have to be in same configuration**
When a referenced object is encountered, finding its definition is
referred back to the container. This means ANY of the input sources
provided to the container can hold this definition, REGARDLESS of format.
* **Spring Python ONLY supports global references**
While Spring Java has different levels of reference like parent, local,
and global, Spring Python only supports global at this time.
In the following subsections, other types of object definitions are given.
Each will also include information about embedding reference objects.
.. _objects-xmlconfig-inner-objects:
Inner Objects
-------------
Inner objects are objects defined inside another structure, and not at the root
level of the XML document. The following shows an alternative configuration of
a *MovieLister* where the *finder* uses a *named inner object*::
The *ColonMovieFinder* is indeed an inner object because it was defined inside
the *MovieLister3* object. Objects defined at the top level have a container-level
name that matches their *id* value. In this case, asking the container for a copy
of *MovieLister3* will yield the top level object. However, named objects develop
a path-like name based on where they are located. In this case, the inner
*ColonMovieFinder* object will have a container-level name of
*MovieLister3.finder.named*.
Typically, neither your code nor other object definitions will have any need
to reference *MovieLister3.finder.named*, but there may be cases where you need
this. The *id* attribute of ColonMovieFinder can be left out (it is optional
for inner objects) like this::
support/movies1.txt
That is slightly more compact, and usually alright because you usually wouldn't
access this object from anywhere. However, if you must, the name in this case
is *MovieLister2.finder.* indicating an anonymous object.
It is important to realize that inner objects have all the same privileges as
top-level objects, meaning that they can also utilize
:ref:`reference objects `,
:ref:`collections `, and inner objects themselves.
.. _objects-xmlconfig-collections:
Collections
-----------
Spring Java supports many types of collections, including lists, sets, frozen
sets, maps, tuples, and Java-style properties. Spring Python supports these
as well. The following configuration shows usage of *dict*, *list*, *props*, *set*,
*frozenset*, and *tuple*::
HelloWorldSpringPythonholderanother copyHello, world!Spring Pythonadministrator@example.orgsupport@example.orgdevelopment@example.orgHello, world!Spring PythonHello, world!Spring PythonHello, world!Spring Python
* some_dict is a Python dictionary with four entries.
* some_list is a Python list with three entries.
* some_props is also a Python dictionary, containing three values.
* some_set is an instance of Python's `mutable set `_.
* some_frozen_set is an instance of Python's `frozen set `_.
* some_tuple is a Python tuple with three values.
.. note::
Java uses maps, Python uses dictionaries
While java calls key-based structures maps, Python calls them dictionaries.
For this reason, the code fragment shows a "dict" entry, which is
one-to-one with Spring Java's "map" definition.
Java also has a *Property* class. Spring Python translates this into a Python
dictionary, making it more like an alternative to the configuring mechanism
of dict.
.. _objects-xmlconfig-constructors:
Constructors
------------
Python functions can have both positional and named arguments. Positional
arguments get assembled into a tuple, and named arguments are assembled into
a dictionary, before being passed to a function call. Spring Python takes
advantage of that option when it comes to constructor calls. The following
block of configuration data shows defining positional constructors::
elemental value
Spring Python will read these and then feed them to the class constructor in
the same order as shown here.
The following code configuration shows named constructor arguments. Spring
Python converts these into keyword arguments, meaning it doesn't matter what
order they are defined::
alt aalt balt calt b
This was copied from the code's test suite, where a test case is used to prove
that order doesn't matter. It is important to note that positional constructor
arguments are fed before named constructors, and that overriding a the same
constructor parameter both by position and by name is not allowed by Python,
and will in turn, generate a run-time error.
It is also valuable to know that you can mix this up and use both.
Values
------
For those of you that used Spring Python before XMLConfig, you may have noticed
that expressing values isn't as succinct as the old format. A good example of
the old :ref:`PyContainer ` format would be::
{
"basichiblueuser" : ("password1", ["ROLE_BASIC", "ASSIGNED_BLUE", "LEVEL_HI"], True),
"basichiorangeuser": ("password2", ["ROLE_BASIC", "ASSIGNED_ORANGE", "LEVEL_HI"], True),
"otherhiblueuser" : ("password3", ["ROLE_OTHER", "ASSIGNED_BLUE", "LEVEL_HI"], True),
"otherhiorangeuser": ("password4", ["ROLE_OTHER", "ASSIGNED_ORANGE", "LEVEL_HI"], True),
"basicloblueuser" : ("password5", ["ROLE_BASIC", "ASSIGNED_BLUE", "LEVEL_LO"], True),
"basicloorangeuser": ("password6", ["ROLE_BASIC", "ASSIGNED_ORANGE", "LEVEL_LO"], True),
"otherloblueuser" : ("password7", ["ROLE_OTHER", "ASSIGNED_BLUE", "LEVEL_LO"], True),
"otherloorangeuser": ("password8", ["ROLE_OTHER", "ASSIGNED_ORANGE", "LEVEL_LO"], True)
}
.. note::
Why do I see components and not objects?
In the beginning, PyContainer was used and it tagged the managed instances
as components. After replacing PyContainer with a more sophisticated IoC
container, the instances are now referred to as objects, however, to
maintain this legacy format, you will see component tags inside
*PyContainerConfig*-based definitions.
While this is very succinct for expressing definitions using as much Python
as possible, that format makes it very hard to embed referenced objects and
inner objects, since PyContainerConfig uses Python's
`eval `_ method to convert
the material.
The following configuration block shows how to configure the same thing for
XMLConfig::
basichiblueuserpassword1ROLE_BASICASSIGNED_BLUELEVEL_HITruebasichiorangeuserpassword2ROLE_BASICASSIGNED_ORANGELEVEL_HITrueotherhiblueuserpassword3ROLE_OTHERASSIGNED_BLUELEVEL_HITrueotherhiorangeuserpassword4ROLE_OTHERASSIGNED_ORANGELEVEL_HITruebasicloblueuserpassword5ROLE_BASICASSIGNED_BLUELEVEL_LOTruebasicloorangeuserpassword6ROLE_BASICASSIGNED_ORANGELEVEL_LOTrueotherloblueuserpassword7ROLE_OTHERASSIGNED_BLUELEVEL_LOTrueotherloorangeuserpassword8ROLE_OTHERASSIGNED_ORANGELEVEL_LOTrue
Of course this is more verbose than the previous block. However, it opens the
door to having a much higher level of detail::
Hello, world!yesThis is workingnoMaybe it's not?Hello, from Spring Python!Spring PythonyesThis is workingnoMaybe it's not?This is a list element inside a tuple.And so is this :)121aba
XMLConfig and basic Python types
--------------------------------
Objects of most commonly used Python types - *str*, *unicode*, *int*, *long*, *float*,
*decimal.Decimal*, *bool* and *complex* - may be expressed in XMLConfig using a
shorthand syntax which allows for a following XMLConfig file::
My stringZażółć gęślą jaźń101000000000000000000000003.1412.34False10+0j
_objects-xmlconfig-inheritance
Object definition inheritance
-----------------------------
XMLConfig's definitions may be stacked up into hierarchies of abstract parents
and their children objects. A child object not only inherits all the properties
and constructor arguments from its parent but it can also easily override any
of the inherited values. This can save a lot of typing when configuring
non-trivial application contexts which would otherwise need to repeat the
same configuration properties over many objects definitions.
An abstract object is identified by having an *abstract="True"* attribute and
the child ones are those which have a *parent* attribute set to ID of an object
from which the properties or constructor arguments should be inherited. Child
objects must not specify the *class* attribute, its value is taken from their
parents.
An object may be both a child and an abstract one.
Here's a hypothetical configuration of a set of services exposed by a server.
Note how you can easily change the CRM environment you're invoking by merely
changing the concrete service's (get_customer_id or get_customer_profile)
parent ID::
192.168.1.15333923393/soap/invoke/get_customer_id/soap/invoke/get_customer_profile
Here's how you can override inherited properties; both get_customer_id and
get_customer_profile object definitions will inherit the path property however
the actual objects returned by the container will use local, overridden,
values of the property::
192.168.1.1533392/DOES-NOT-EXIST/soap/invoke/get_customer_id/soap/invoke/get_customer_profile
.. highlight:: python
If you need to get an abstract object from a container, use the .get_object's
*ignore_abstract* parameter, otherwise *springpython.container.AbstractObjectException*
will be raised. Observe the difference::
# .. skip creating the context
# No exception will be raised, even though 'service' is an abstract object
service = ctx.get_object("service", ignore_abstract=True)
# Will show the object
print service
# Will raise AbstractObjectException
service = ctx.get_object("service")