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