001/*
002 *   Licensed to the Apache Software Foundation (ASF) under one
003 *   or more contributor license agreements.  See the NOTICE file
004 *   distributed with this work for additional information
005 *   regarding copyright ownership.  The ASF licenses this file
006 *   to you under the Apache License, Version 2.0 (the
007 *   "License"); you may not use this file except in compliance
008 *   with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *   Unless required by applicable law or agreed to in writing,
013 *   software distributed under the License is distributed on an
014 *   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *   KIND, either express or implied.  See the License for the
016 *   specific language governing permissions and limitations
017 *   under the License.
018 *
019 */
020package org.apache.directory.api.ldap.model.message;
021
022
023import org.apache.directory.api.i18n.I18n;
024
025
026/**
027 * A search scope enumerated type.
028 *
029 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
030 */
031public enum SearchScope
032{
033    OBJECT(0, "base"),
034    ONELEVEL(1, "one"),
035    SUBTREE(2, "sub");
036
037    /** 
038     * The corresponding LDAP scope constant value as defined in 
039     * RFC 4511
040     */
041    private final int scope;
042
043    /**
044     * The LDAP URL string value of either base, one or sub as defined in RFC
045     * 2255.
046     * 
047     * @see <a href="http://www.faqs.org/rfcs/rfc2255.html">RFC 2255</a>
048     */
049    private final String ldapUrlValue;
050
051
052    /**
053     * Creates a new instance of SearchScope based on the respective 
054     * scope constant.
055     *
056     * @param scope the scope constant
057     * @param ldapUrlValue LDAP URL scope string value: base, one, or sub
058     */
059    private SearchScope( int scope, String ldapUrlValue )
060    {
061        this.scope = scope;
062        this.ldapUrlValue = ldapUrlValue;
063    }
064
065
066    /**
067     * Gets the LDAP URL value for the scope: according to RFC 2255 this is 
068     * either base, one, or sub.
069     * 
070     * @see <a href="http://www.faqs.org/rfcs/rfc2255.html">RFC 2255</a>
071     */
072    public String getLdapUrlValue()
073    {
074        return ldapUrlValue;
075    }
076
077
078    /**
079     * Gets the corresponding scope constant value as defined in 
080     * RFC 4511.
081     * 
082     * @return the scope
083     */
084    public int getScope()
085    {
086        return scope;
087    }
088
089
090    /**
091     * Gets the SearchScope enumerated type for the corresponding 
092     * scope numeric value.
093     *
094     * @param scope the numeric value to get SearchScope for
095     * @return the SearchScope enumerated type for the scope numeric value
096     */
097    public static SearchScope getSearchScope( int scope )
098    {
099        switch ( scope )
100        {
101            case 0:
102                return OBJECT;
103
104            case 1:
105                return ONELEVEL;
106
107            case 2:
108                return SUBTREE;
109
110            default:
111                throw new IllegalArgumentException( I18n.err( I18n.ERR_04160, scope ) );
112        }
113    }
114
115
116    /**
117     * Gets the SearchScope enumerated type for the corresponding 
118     * LDAP URL scope value of either base, one or sub.
119     *
120     * @param ldapUrlValue the LDAP URL scope value to get SearchScope for
121     * @return the SearchScope enumerated type for the LDAP URL scope value
122     */
123    public static int getSearchScope( String ldapUrlValue )
124    {
125        if ( "base".equalsIgnoreCase( ldapUrlValue ) )
126        {
127            return OBJECT.getScope();
128        }
129        else if ( "one".equalsIgnoreCase( ldapUrlValue ) )
130        {
131            return ONELEVEL.getScope();
132        }
133        else if ( "sub".equalsIgnoreCase( ldapUrlValue ) )
134        {
135            return SUBTREE.getScope();
136        }
137        else
138        {
139            throw new IllegalArgumentException( I18n.err( I18n.ERR_04161, ldapUrlValue ) );
140        }
141    }
142
143
144    /**
145     * {@inheritDoc}
146     */
147    public String toString()
148    {
149        return ldapUrlValue;
150    }
151}