001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2009 Sun Microsystems, Inc.
025 */
026
027package org.forgerock.opendj.ldap;
028
029import java.util.Arrays;
030import java.util.Collections;
031import java.util.List;
032
033/**
034 * A Search operation alias dereferencing policy as defined in RFC 4511 section
035 * 4.5.1.3 is used to indicate whether or not alias entries (as defined in RFC
036 * 4512) are to be dereferenced during stages of a Search operation. The act of
037 * dereferencing an alias includes recursively dereferencing aliases that refer
038 * to aliases.
039 *
040 * @see <a href="http://tools.ietf.org/html/rfc4511#section-4.5.1.3">RFC 4511 -
041 *      Lightweight Directory Access Protocol (LDAP): The Protocol </a>
042 * @see <a href="http://tools.ietf.org/html/rfc4512">RFC 4512 - Lightweight
043 *      Directory Access Protocol (LDAP): Directory Information Models </a>
044 */
045public final class DereferenceAliasesPolicy {
046    private static final DereferenceAliasesPolicy[] ELEMENTS = new DereferenceAliasesPolicy[4];
047
048    private static final List<DereferenceAliasesPolicy> IMMUTABLE_ELEMENTS = Collections
049            .unmodifiableList(Arrays.asList(ELEMENTS));
050
051    /**
052     * Do not dereference aliases in searching or in locating the base object of
053     * a Search operation.
054     */
055    public static final DereferenceAliasesPolicy NEVER = register(0, "never");
056
057    /**
058     * While searching subordinates of the base object, dereference any alias
059     * within the scope of the Search operation. Dereferenced objects become the
060     * vertices of further search scopes where the Search operation is also
061     * applied. If the search scope is {@code WHOLE_SUBTREE}, the Search
062     * continues in the subtree(s) of any dereferenced object. If the search
063     * scope is {@code SINGLE_LEVEL}, the search is applied to any dereferenced
064     * objects and is not applied to their subordinates.
065     */
066    public static final DereferenceAliasesPolicy IN_SEARCHING = register(1, "search");
067
068    /**
069     * Dereference aliases in locating the base object of a Search operation,
070     * but not when searching subordinates of the base object.
071     */
072    public static final DereferenceAliasesPolicy FINDING_BASE = register(2, "find");
073
074    /**
075     * Dereference aliases both in searching and in locating the base object of
076     * a Search operation.
077     */
078    public static final DereferenceAliasesPolicy ALWAYS = register(3, "always");
079
080    /**
081     * Returns the alias dereferencing policy having the specified integer value
082     * as defined in RFC 4511 section 4.5.1.
083     *
084     * @param intValue
085     *            The integer value of the alias dereferencing policy.
086     * @return The dereference aliases policy, or {@code null} if there was no
087     *         alias dereferencing policy associated with {@code intValue}.
088     */
089    public static DereferenceAliasesPolicy valueOf(final int intValue) {
090        if (intValue < 0 || intValue >= ELEMENTS.length) {
091            return null;
092        }
093        return ELEMENTS[intValue];
094    }
095
096    /**
097     * Returns an unmodifiable list containing the set of available alias
098     * dereferencing policies indexed on their integer value as defined in RFC
099     * 4511 section 4.5.1.
100     *
101     * @return An unmodifiable list containing the set of available alias
102     *         dereferencing policies.
103     */
104    public static List<DereferenceAliasesPolicy> values() {
105        return IMMUTABLE_ELEMENTS;
106    }
107
108    /**
109     * Creates and registers a new alias dereferencing policy with the
110     * application.
111     *
112     * @param intValue
113     *            The integer value of the alias dereferencing policy as defined
114     *            in RFC 4511 section 4.5.1.
115     * @param name
116     *            The name of the alias dereferencing policy.
117     * @return The new alias dereferencing policy.
118     */
119    private static DereferenceAliasesPolicy register(final int intValue, final String name) {
120        final DereferenceAliasesPolicy t = new DereferenceAliasesPolicy(intValue, name);
121        ELEMENTS[intValue] = t;
122        return t;
123    }
124
125    private final int intValue;
126
127    private final String name;
128
129    /** Prevent direct instantiation. */
130    private DereferenceAliasesPolicy(final int intValue, final String name) {
131        this.intValue = intValue;
132        this.name = name;
133    }
134
135    /** {@inheritDoc} */
136    @Override
137    public boolean equals(final Object obj) {
138        if (this == obj) {
139            return true;
140        } else if (obj instanceof DereferenceAliasesPolicy) {
141            return this.intValue == ((DereferenceAliasesPolicy) obj).intValue;
142        } else {
143            return false;
144        }
145    }
146
147    /** {@inheritDoc} */
148    @Override
149    public int hashCode() {
150        return intValue;
151    }
152
153    /**
154     * Returns the integer value of this alias dereferencing policy as defined
155     * in RFC 4511 section 4.5.1.
156     *
157     * @return The integer value of this alias dereferencing policy.
158     */
159    public int intValue() {
160        return intValue;
161    }
162
163    /**
164     * Returns the string representation of this alias dereferencing policy.
165     *
166     * @return The string representation of this alias dereferencing policy.
167     */
168    @Override
169    public String toString() {
170        return name;
171    }
172}