001package com.nimbusds.infinispan.persistence.ldap;
002
003
004import java.util.Set;
005
006import com.nimbusds.infinispan.persistence.common.InfinispanEntry;
007import com.unboundid.ldap.sdk.DN;
008import com.unboundid.ldap.sdk.RDN;
009
010
011/**
012 * Interface for transforming between Infinispan entries (key / value pair and
013 * metadata) and a corresponding LDAP entry (consisting of a Distinguished Name
014 * (DN) and attributes). Implementations must be thread-safe.
015 *
016 * <p>To specify an entry transformer for a given Infinispan cache that is
017 * backed by an LDAP store, provide its class name to the
018 * {@link com.nimbusds.infinispan.persistence.ldap.LDAPStoreConfiguration
019 * store configuration}.
020 */
021public interface LDAPEntryTransformer<K,V> {
022
023
024        /**
025         * Returns the names of the LDAP directory attributes that may be
026         * modified when an Infinispan entry is updated or replaced via the
027         * {@link java.util.Map} interface. Attributes that identify the LDAP
028         * entry (form its Relative Distinguished Name (RDN)) and the
029         * attribute {@code objectClass} that defined its classes are typically
030         * immutable for an entry and therefore must not be included.
031         * Operational (meta) attributes must not be included either.
032         *
033         * <p>Example:
034         *
035         * <ul>
036         *     <li>Java object {@code User} with fields {@code id},
037         *     {@code givenName}, {@code surname} and {@code email}.
038         *     <li>These fields map to the LDAP attributes {@code uid},
039         *     {@code givenName}, {@code sn} and {@code mail} of the LDAP class
040         *     {@code inetOrgPerson}.
041         *     <li>Of of the above LDAP attributes, {@code uid} is never
042         *     changed for a user, and only {@code givenName}, {@code sn} and
043         *     {@code mail} may be updated. This method should then return the
044         *     set {@code givenName, sn, mail}.
045         * </ul>
046         *
047         * @return The names of the modifiable directory attributes. Must not
048         *         include {@code objectClass}, attributes that form the
049         *         Relative Distinguished Name (RDN), or operational
050         *         attributes. Must not be empty or {@code null}.
051         */
052        Set<String> getModifiableAttributes();
053
054
055        /**
056         * Returns {@code true} if any of the {@link #getModifiableAttributes
057         * modifiable attributes} may include options (such as a flag
058         * indicating a binary value, or a language tag).
059         *
060         * @return {@code true} if any of the modifiable attributes may
061         *         include options (such as a binary flag or a language tag),
062         *         else {@code false}.
063         */
064        boolean includesAttributesWithOptions();
065
066
067        /**
068         * Resolves the specified Infinispan entry key to a Relative
069         * Distinguished Name (RDN) for the matching LDAP directory entry.
070         *
071         * <p>Example:
072         *
073         * <ul>
074         *     <li>Java object {@code User} keyed by its {@code id} field which
075         *     is a {@link java.lang.String}.
076         *     <li>The Java {@code id} fields maps to the LDAP attribute
077         *     {@code uid}.
078         *     <li>The {@code "cae7t"} key must then resolve to the RDN
079         *     {@code uid=cae7t}.
080         * </ul>
081         *
082         * <p>Composite keys may map to RDNs with multiple attributes, e.g.
083         * {@code uid=cae7t+ou=sales}.
084         *
085         * @param key The key. Not {@code null}.
086         *
087         * @return The resolved RDN.
088         */
089        RDN resolveRDN(final K key);
090        
091
092        /**
093         * Transforms the specified Infinispan entry (key / value pair with
094         * optional metadata) to an LDAP directory entry ready to be written.
095         * The LDAP entry may be supplied with an {@link LDAPWriteStrategy}.
096         *
097         * <p>Example:
098         *
099         * <ul>
100         *     <li>Base DN: {@code ou=people,dc=wondlerland,dc=net}
101         *     <li>Key: cae7t
102         *     <li>Value: Java POJO with fields {@code uid=cae7t},
103         *         {@code givenName=Alice}, {@code surname=Adams} and
104         *         {@code email=alice@wonderland.net}.
105         *     <li>Metadata: Specifies the entry expiration and other
106         *         properties.
107         * </ul>
108         *
109         * <p>Resulting LDAP entry:</p>
110         *
111         * <pre>
112         * dn: uid=cae7t,ou=people,dc=wondlerland,dc=net
113         * objectClass: top
114         * objectClass: person
115         * objectClass: organizationalPerson
116         * objectClass: inetOrgPerson
117         * uid: cae7t
118         * cn: Alice Adams
119         * sn: Adams
120         * givenName: Alice
121         * mail: alice@wonderland.net
122         * </pre>
123         *
124         * @param baseDN          The Distinguished Name (DN) of the directory
125         *                        branch where the entry is located. Not
126         *                        {@code null}.
127         * @param infinispanEntry The Infinispan entry. Not {@code null}.
128         *
129         * @return The LDAP entry.
130         */
131        LDAPEntry toLDAPEntry(final DN baseDN, final InfinispanEntry<K,V> infinispanEntry);
132
133
134        /**
135         * Transforms the specified LDAP entry to an Infinispan entry (key /
136         * value / metadata triple).
137         *
138         * <p>Example:
139         *
140         * <p>LDAP entry:</p>
141         *
142         * <pre>
143         * dn: uid=cae7t,ou=people,dc=wondlerland,dc=net
144         * objectClass: top
145         * objectClass: person
146         * objectClass: organizationalPerson
147         * objectClass: inetOrgPerson
148         * uid: cae7t
149         * cn: Alice Adams
150         * sn: Adams
151         * givenName: Alice
152         * mail: alice@wonderland.net
153         * </pre>
154         *
155         * <p>Resulting key / value pair:
156         *
157         * <ul>
158         *     <li>Key: cae7t
159         *     <li>Value: Java POJO with fields {@code uid=cae7t},
160         *         {@code givenName=Alice}, {@code surname=Adams} and
161         *         {@code email=alice@wonderland.net}.
162         *     <li>Metadata: Default metadata (no expiration, etc).
163         * </ul>
164         *
165         * @param ldapEntry The LDAP entry. Not {@code null}.
166         *
167         * @return The Infinispan entry (key / value pair with optional
168         *         metadata).
169         */
170        InfinispanEntry<K,V> toInfinispanEntry(final LDAPEntry ldapEntry);
171}