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     * @return the LDAP URL value
073     */
074    public String getLdapUrlValue()
075    {
076        return ldapUrlValue;
077    }
078
079
080    /**
081     * Gets the corresponding scope constant value as defined in 
082     * RFC 4511.
083     * 
084     * @return the scope
085     */
086    public int getScope()
087    {
088        return scope;
089    }
090
091
092    /**
093     * Gets the SearchScope enumerated type for the corresponding 
094     * scope numeric value.
095     *
096     * @param scope the numeric value to get SearchScope for
097     * @return the SearchScope enumerated type for the scope numeric value
098     */
099    public static SearchScope getSearchScope( int scope )
100    {
101        switch ( scope )
102        {
103            case 0:
104                return OBJECT;
105
106            case 1:
107                return ONELEVEL;
108
109            case 2:
110                return SUBTREE;
111
112            default:
113                throw new IllegalArgumentException( I18n.err( I18n.ERR_04160, scope ) );
114        }
115    }
116
117
118    /**
119     * Gets the SearchScope associated with a scope String
120     *
121     * @param scope The scope we are looking for
122     * @return the scope
123     */
124    public SearchScope getScope( String scope )
125    {
126        if ( "base".equalsIgnoreCase( scope ) )
127        {
128            return OBJECT;
129        }
130        else if ( "one".equalsIgnoreCase( scope ) )
131        {
132            return ONELEVEL;
133        }
134        else if ( "sub".equalsIgnoreCase( scope ) )
135        {
136            return SUBTREE;
137        }
138        else
139        {
140            throw new IllegalArgumentException( I18n.err( I18n.ERR_04161, scope ) );
141        }
142    }
143
144
145    /**
146     * Gets the SearchScope enumerated type for the corresponding 
147     * scope value of either base, one or sub.
148     *
149     * @param scope the scope value to get SearchScope for
150     * @return the SearchScope enumerated type for the LDAP URL scope value
151     */
152    public static int getSearchScope( String scope )
153    {
154        if ( "base".equalsIgnoreCase( scope ) )
155        {
156            return OBJECT.getScope();
157        }
158        else if ( "one".equalsIgnoreCase( scope ) )
159        {
160            return ONELEVEL.getScope();
161        }
162        else if ( "sub".equalsIgnoreCase( scope ) )
163        {
164            return SUBTREE.getScope();
165        }
166        else
167        {
168            throw new IllegalArgumentException( I18n.err( I18n.ERR_04161, scope ) );
169        }
170    }
171
172
173    /**
174     * {@inheritDoc}
175     */
176    public String toString()
177    {
178        return ldapUrlValue;
179    }
180}