Adjusted examples and sections and added some xrefs.
This commit is contained in:
Ulrik Sandberg
@@ -1,26 +1,26 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||||
<chapter>
|
||||
<chapter id="odm">
|
||||
<title>Object-Directory Mapping (ODM)</title>
|
||||
|
||||
<section>
|
||||
<sect1 id="odm-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>Relational mapping frameworks like Hibernate and JPA have offered
|
||||
developers the ability to use annotations to map database tables to Java
|
||||
objects for some time. The Spring Framework LDAP project now offers the
|
||||
same ability with respect to directories through the use of the
|
||||
<package>org.springframework.ldap.odm</package> package.</para>
|
||||
</section>
|
||||
<code>org.springframework.ldap.odm</code> package.</para>
|
||||
</sect1>
|
||||
|
||||
<section>
|
||||
<sect1 id="odm-odmmanager">
|
||||
<title>OdmManager</title>
|
||||
|
||||
<para>The
|
||||
<interfacename>org.springframework.ldap.odm.OdmManager</interfacename>
|
||||
<code>org.springframework.ldap.odm.OdmManager</code>
|
||||
interface, and its implementation, is the central class in the ODM
|
||||
package. The <interfacename>OdmManager</interfacename> orchestrates the
|
||||
package. The <code>OdmManager</code> orchestrates the
|
||||
process of reading objects from the directory and mapping the data to
|
||||
annotated Java object classes. This interface provides access to the
|
||||
underlying directory instance through the following methods:</para>
|
||||
@@ -56,48 +56,56 @@
|
||||
|
||||
<para>A reference to an implementation of this interface can be obtained
|
||||
through the
|
||||
<classname>org.springframework.ldap.odm.core.impl.OdmManagerImplFactoryBean</classname>.
|
||||
<code>org.springframework.ldap.odm.core.impl.OdmManagerImplFactoryBean</code>.
|
||||
A basic configuration of this factory would be as follows:</para>
|
||||
|
||||
<example>
|
||||
<title>Example 1.1 Configuring the OdmManager Factory</title>
|
||||
|
||||
<para><code><beans> ... <bean id="odmManager"
|
||||
class="org.springframework.ldap.odm.core.impl.OdmManagerImplFactoryBean">
|
||||
<property name="converterManager" ref="converterManager" />
|
||||
<property name="contextSource" ref="contextSource" /> <property
|
||||
name="managedClasses"> <set>
|
||||
<value>com.ldap.dao.SimplePerson</value> </set>
|
||||
</property> </bean> ... </beans></code></para>
|
||||
<title>Configuring the OdmManager Factory</title>
|
||||
<programlisting><![CDATA[
|
||||
<beans>
|
||||
...
|
||||
<bean id="odmManager" class="org.springframework.ldap.odm.core.impl.OdmManagerImplFactoryBean">
|
||||
<property name="converterManager" ref="converterManager" />
|
||||
<property name="contextSource" ref="contextSource" />
|
||||
<property name="managedClasses">
|
||||
<set>
|
||||
<value>com.example.dao.SimplePerson</value>
|
||||
</set>
|
||||
</property>
|
||||
</bean>
|
||||
...
|
||||
</beans>
|
||||
]]></programlisting>
|
||||
</example>
|
||||
|
||||
<para>The factory requires the list of entity classes to be managed by the
|
||||
<interfacename>OdmManager</interfacename> to be explicitly declared. These
|
||||
classes should be properly annotated as defined in the next setion. The
|
||||
<property>converterManager</property> referenced in the above definition
|
||||
is described in section 4: Type Conversion.</para>
|
||||
</section>
|
||||
<code>OdmManager</code> to be explicitly declared. These
|
||||
classes should be properly annotated as defined in the next section. The
|
||||
<code>converterManager</code> referenced in the above definition
|
||||
is described in <xref
|
||||
linkend="odm-typeconversion" />.</para>
|
||||
</sect1>
|
||||
|
||||
<section>
|
||||
<sect1 id="odm-annotations">
|
||||
<title>Annotations</title>
|
||||
|
||||
<para>Entity classes managed by the
|
||||
<interfacename>OdmManager</interfacename> are required to be annotated
|
||||
<code>OdmManager</code> are required to be annotated
|
||||
with the annotations in the
|
||||
<package>org.springframework.ldap.odm.annotations</package> package. The
|
||||
<code>org.springframework.ldap.odm.annotations</code> package. The
|
||||
available annotations are:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><code>@Entry</code> - Class level annotation indicating the
|
||||
<property>objectClass</property> definitions to which the entity
|
||||
<code>objectClass</code> definitions to which the entity
|
||||
maps.<emphasis> (required)</emphasis></para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><code>@Id</code> - Indicates the entity DN; the field declaring
|
||||
this attribute must be a derivative of the
|
||||
<classname>javax.naming.Name</classname> class.
|
||||
<code>javax.naming.Name</code> class.
|
||||
<emphasis>(required)</emphasis></para>
|
||||
</listitem>
|
||||
|
||||
@@ -109,7 +117,7 @@
|
||||
<listitem>
|
||||
<para><code>@Transient</code> - Indicates the field is not persistent
|
||||
and should be ignored by the
|
||||
<interfacename>OdmManager</interfacename>.</para>
|
||||
<code>OdmManager</code>.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
@@ -123,7 +131,7 @@
|
||||
|
||||
<simpara>The <code>@Id</code> annotation is used to map the distinguished
|
||||
name of the entry to a field. The field must be an instance of
|
||||
<classname>javax.naming.Name</classname> or a subclass of it.</simpara>
|
||||
<code>javax.naming.Name</code> or a subclass of it.</simpara>
|
||||
|
||||
<simpara>The <code>@Attribute</code> annotation is used to map object
|
||||
class fields to entity fields. <code>@Attribute</code> is required to
|
||||
@@ -134,39 +142,39 @@
|
||||
based or string based by the LDAP JNDI provider.</simpara>
|
||||
|
||||
<simpara>The <code>@Transient</code> annotation is used to indicate the
|
||||
field should be ignored by the <interfacename>OdmManager</interfacename>
|
||||
field should be ignored by the <code>OdmManager</code>
|
||||
and not mapped to an underlying LDAP property.</simpara>
|
||||
</section>
|
||||
</sect1>
|
||||
|
||||
<section>
|
||||
<sect1 id="odm-typeconversion">
|
||||
<title>Type Conversion</title>
|
||||
|
||||
<para>The <interfacename>OdmManager</interfacename> relies on the
|
||||
<package>org.springframework.ldap.odm.typeconversion</package> package to
|
||||
<para>The <code>OdmManager</code> relies on the
|
||||
<code>org.springframework.ldap.odm.typeconversion</code> package to
|
||||
convert LDAP attributes to Java fields. The main interface in this class
|
||||
is the
|
||||
<interfacename>org.springframework.ldap.odm.typeconversion.ConverterManager</interfacename>.
|
||||
The default <interfacename>ConverterManager</interfacename> implementation
|
||||
<code>org.springframework.ldap.odm.typeconversion.ConverterManager</code>.
|
||||
The default <code>ConverterManager</code> implementation
|
||||
uses the following algorithm when parsing objects to convert
|
||||
fields:<orderedlist>
|
||||
<listitem>
|
||||
<para>Try to find and use a <interfacename>Converter</interfacename>
|
||||
registered for the <property>fromClass</property>,
|
||||
<property>syntax</property> and <property>toClass</property> and use
|
||||
<para>Try to find and use a <code>Converter</code>
|
||||
registered for the <code>fromClass</code>,
|
||||
<code>syntax</code> and <code>toClass</code> and use
|
||||
it.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If this fails, then if the <property>toClass</property>
|
||||
<para>If this fails, then if the <code>toClass</code>
|
||||
<code><methodname>isAssignableFrom</methodname></code> the
|
||||
<property>fromClass</property> then just assign it.</para>
|
||||
<code>fromClass</code> then just assign it.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If this fails try to find and use a
|
||||
<code><interfacename>Converter</interfacename></code> registered for
|
||||
the <property>fromClass</property> and the
|
||||
<property>toClass</property> ignoring the syntax.</para>
|
||||
<code><code>Converter</code></code> registered for
|
||||
the <code>fromClass</code> and the
|
||||
<code>toClass</code> ignoring the syntax.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
@@ -175,85 +183,109 @@
|
||||
</listitem>
|
||||
</orderedlist></para>
|
||||
|
||||
<para>Implementations of the <classname>ConverterManager</classname>
|
||||
<para>Implementations of the <code>ConverterManager</code>
|
||||
interface can be obtained from the
|
||||
<classname>org.springframework.ldap.odm.typeconversion.impl.ConvertManagerFactoryBean</classname>.
|
||||
<code>org.springframework.ldap.odm.typeconversion.impl.ConvertManagerFactoryBean</code>.
|
||||
The factory bean requires converter configurations to be declared in the
|
||||
bean configuration. </para>
|
||||
|
||||
<para>The converterConfig property accepts a set of
|
||||
<classname>ConverterConfig</classname> classes, each one defining some
|
||||
<code>ConverterConfig</code> classes, each one defining some
|
||||
conversion logic. A converter config is an instance of
|
||||
<classname>org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean.ConverterConfig</classname>.
|
||||
<code>org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean.ConverterConfig</code>.
|
||||
The config defines a set of source classes, the set of target classes, and
|
||||
an implementation of the
|
||||
<interfacename>com.springframework.ldap.odm.typeconversion.impl.Converter</interfacename>
|
||||
<code>com.springframework.ldap.odm.typeconversion.impl.Converter</code>
|
||||
interface which provides the logic to convert from the
|
||||
<property>fromClass</property> to the <property>toClass</property>. A
|
||||
sample configuration is provided in Example 1.3. </para>
|
||||
<code>fromClass</code> to the <code>toClass</code>. A
|
||||
sample configuration is provided in the following example:</para>
|
||||
|
||||
<example>
|
||||
<title>Example 1.3 Configuring the Converter Manager Factory</title>
|
||||
|
||||
<para><code><bean id="fromStringConverter"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.converters.FromStringConverter"
|
||||
/> <bean id="toStringConverter"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.converters.ToStringConverter"
|
||||
/> <bean id="converterManager"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean">
|
||||
<property name="converterConfig"> <set> <bean
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean$ConverterConfig">
|
||||
<property name="fromClasses"> <set>
|
||||
<value>java.lang.String</value> </set>
|
||||
</property> <property name="toClasses"> <set>
|
||||
<value>java.lang.Byte</value>
|
||||
<value>java.lang.Short</value>
|
||||
<value>java.lang.Integer</value>
|
||||
<value>java.lang.Long</value>
|
||||
<value>java.lang.Float</value>
|
||||
<value>java.lang.Double</value>
|
||||
<value>java.lang.Boolean</value> </set>
|
||||
</property> <property name="converter"
|
||||
ref="fromStringConverter" /> </bean> <bean
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean$ConverterConfig">
|
||||
<property name="fromClasses"> <set>
|
||||
<value>java.lang.Byte</value>
|
||||
<value>java.lang.Short</value>
|
||||
<value>java.lang.Integer</value>
|
||||
<value>java.lang.Long</value>
|
||||
<value>java.lang.Float</value>
|
||||
<value>java.lang.Double</value>
|
||||
<value>java.lang.Boolean</value> </set>
|
||||
</property> <property name="toClasses"> <set>
|
||||
<value>java.lang.String</value> </set>
|
||||
</property> <property name="converter" ref="toStringConverter"
|
||||
/> </bean> </set> </property> </bean>
|
||||
</code></para>
|
||||
<title>Configuring the Converter Manager Factory</title>
|
||||
<programlisting><![CDATA[
|
||||
<bean id="fromStringConverter"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.converters.FromStringConverter" />
|
||||
<bean id="toStringConverter"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.converters.ToStringConverter" />
|
||||
<bean id="converterManager"
|
||||
class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean">
|
||||
<property name="converterConfig">
|
||||
<set>
|
||||
<bean class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean$ConverterConfig">
|
||||
<property name="fromClasses">
|
||||
<set>
|
||||
<value>java.lang.String</value>
|
||||
</set>
|
||||
</property>
|
||||
<property name="toClasses">
|
||||
<set>
|
||||
<value>java.lang.Byte</value>
|
||||
<value>java.lang.Short</value>
|
||||
<value>java.lang.Integer</value>
|
||||
<value>java.lang.Long</value>
|
||||
<value>java.lang.Float</value>
|
||||
<value>java.lang.Double</value>
|
||||
<value>java.lang.Boolean</value>
|
||||
</set>
|
||||
</property>
|
||||
<property name="converter" ref="fromStringConverter" />
|
||||
</bean>
|
||||
<bean class="org.springframework.ldap.odm.typeconversion.impl.ConverterManagerFactoryBean$ConverterConfig">
|
||||
<property name="fromClasses">
|
||||
<set>
|
||||
<value>java.lang.Byte</value>
|
||||
<value>java.lang.Short</value>
|
||||
<value>java.lang.Integer</value>
|
||||
<value>java.lang.Long</value>
|
||||
<value>java.lang.Float</value>
|
||||
<value>java.lang.Double</value>
|
||||
<value>java.lang.Boolean</value>
|
||||
</set>
|
||||
</property>
|
||||
<property name="toClasses">
|
||||
<set>
|
||||
<value>java.lang.String</value>
|
||||
</set>
|
||||
</property>
|
||||
<property name="converter" ref="toStringConverter" />
|
||||
</bean>
|
||||
</set>
|
||||
</property>
|
||||
</bean>
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
</sect1>
|
||||
|
||||
<section>
|
||||
<sect1 id="odm-execution">
|
||||
<title>Execution</title>
|
||||
|
||||
<para>After all components are configured, directory interaction can be
|
||||
acheived through a reference to the
|
||||
<interfacename>OdmManager</interfacename> as shown in Example 1.4:</para>
|
||||
<code>OdmManager</code> as shown in this example:</para>
|
||||
|
||||
<example>
|
||||
<title>Example 1.4 Execution</title>
|
||||
|
||||
<para><code>public class App { private static Log log =
|
||||
LogFactory.getLog(App.class); private static final SearchControls
|
||||
searchControls = new SearchControls(SearchControls.SUBTREE_SCOPE, 100,
|
||||
10000, null, true, false); public static void main( String[] args ) {
|
||||
try { ApplicationContext context = new
|
||||
ClassPathXmlApplicationContext("applicationContext.xml"); OdmManager
|
||||
manager = (OdmManager) context.getBean("odmManager");
|
||||
List<SimplePerson> people = manager.search(SimplePerson.class, new
|
||||
DistinguishedName("dc=example,dc=com"), "uid=*", searchControls);
|
||||
log.info("People found: " + people.size()); for (SimplePerson person :
|
||||
people) { log.info( person ); } } catch (Exception e) {
|
||||
e.printStackTrace(); } } }</code></para>
|
||||
<title>Execution</title>
|
||||
<programlisting><![CDATA[
|
||||
public class App {
|
||||
private static Log log = LogFactory.getLog(App.class);
|
||||
private static final SearchControls searchControls =
|
||||
new SearchControls(SearchControls.SUBTREE_SCOPE, 100, 10000, null, true, false);
|
||||
public static void main( String[] args ) {
|
||||
try {
|
||||
ApplicationContext context = new ClassPathXmlApplicationContext("applicationContext.xml");
|
||||
OdmManager manager = (OdmManager) context.getBean("odmManager");
|
||||
List<SimplePerson> people = manager.search(
|
||||
SimplePerson.class, new DistinguishedName("dc=example,dc=com"), "uid=*", searchControls);
|
||||
log.info("People found: " + people.size());
|
||||
for (SimplePerson person : people) {
|
||||
log.info( person );
|
||||
}
|
||||
} catch (Exception e) {
|
||||
e.printStackTrace();
|
||||
}
|
||||
}
|
||||
}
|
||||
]]></programlisting>
|
||||
</example>
|
||||
</section>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
Reference in New Issue
Block a user