jdk/src/share/classes/javax/naming/directory/Attributes.java
author duke
Sat, 01 Dec 2007 00:00:00 +0000
changeset 2 90ce3da70b43
child 5506 202f599c92aa
permissions -rw-r--r--
Initial load
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
 * Copyright 1999-2004 Sun Microsystems, Inc.  All Rights Reserved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Sun designates this
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
 * by Sun in the LICENSE file that accompanied this code.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
 * CA 95054 USA or visit www.sun.com if you need additional information or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
 * have any questions.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
package javax.naming.directory;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
import java.util.Hashtable;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
import java.util.Enumeration;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
import javax.naming.NamingException;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
import javax.naming.NamingEnumeration;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
  * This interface represents a collection of attributes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
  *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
  * In a directory, named objects can have associated with them
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
  * attributes.  The Attributes interface represents a collection of attributes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
  * For example, you can request from the directory the attributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
  * associated with an object.  Those attributes are returned in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
  * an object that implements the Attributes interface.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
  *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
  * Attributes in an object that implements the  Attributes interface are
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
  * unordered. The object can have zero or more attributes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
  * Attributes is either case-sensitive or case-insensitive (case-ignore).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
  * This property is determined at the time the Attributes object is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
  * created. (see BasicAttributes constructor for example).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
  * In a case-insensitive Attributes, the case of its attribute identifiers
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
  * is ignored when searching for an attribute, or adding attributes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
  * In a case-sensitive Attributes, the case is significant.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
  *<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
  * Note that updates to Attributes (such as adding or removing an attribute)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
  * do not affect the corresponding representation in the directory.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
  * Updates to the directory can only be effected
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
  * using operations in the DirContext interface.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
  *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
  * @author Rosanna Lee
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
  * @author Scott Seligman
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
  *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
  * @see DirContext#getAttributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
  * @see DirContext#modifyAttributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
  * @see DirContext#bind
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
  * @see DirContext#rebind
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
  * @see DirContext#createSubcontext
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
  * @see DirContext#search
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
  * @see BasicAttributes
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
  * @since 1.3
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
  */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
public interface Attributes extends Cloneable, java.io.Serializable {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
      * Determines whether the attribute set ignores the case of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
      * attribute identifiers when retrieving or adding attributes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
      * @return true if case is ignored; false otherwise.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
    boolean isCaseIgnored();
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
      * Retrieves the number of attributes in the attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
      * @return The nonnegative number of attributes in this attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
    int size();
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
      * Retrieves the attribute with the given attribute id from the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
      * attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
      * @param attrID The non-null id of the attribute to retrieve.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
      *           If this attribute set ignores the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
      *           case of its attribute ids, the case of attrID
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
      *           is ignored.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
      * @return The attribute identified by attrID; null if not found.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
      * @see #put
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
      * @see #remove
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
    Attribute get(String attrID);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
      * Retrieves an enumeration of the attributes in the attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
      * The effects of updates to this attribute set on this enumeration
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
      * are undefined.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
      * @return A non-null enumeration of the attributes in this attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
      *         Each element of the enumeration is of class <tt>Attribute</tt>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
      *         If attribute set has zero attributes, an empty enumeration
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
      *         is returned.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
    NamingEnumeration<? extends Attribute> getAll();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
      * Retrieves an enumeration of the ids of the attributes in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
      * attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
      * The effects of updates to this attribute set on this enumeration
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
      * are undefined.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
      * @return A non-null enumeration of the attributes' ids in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
      *         this attribute set. Each element of the enumeration is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
      *         of class String.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
      *         If attribute set has zero attributes, an empty enumeration
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
      *         is returned.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
    NamingEnumeration<String> getIDs();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
      * Adds a new attribute to the attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
      * @param attrID   non-null The id of the attribute to add.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
      *           If the attribute set ignores the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
      *           case of its attribute ids, the case of attrID
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
      *           is ignored.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
      * @param val      The possibly null value of the attribute to add.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
      *                 If null, the attribute does not have any values.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
      * @return The Attribute with attrID that was previous in this attribute set;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
      *         null if no such attribute existed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
      * @see #remove
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
    Attribute put(String attrID, Object val);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
      * Adds a new attribute to the attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
      * @param attr     The non-null attribute to add.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
      *                 If the attribute set ignores the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
      *                 case of its attribute ids, the case of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
      *                 attr's identifier is ignored.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
      * @return The Attribute with the same ID as attr that was previous
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
      *         in this attribute set;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
      *         null if no such attribute existed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
      * @see #remove
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
    Attribute put(Attribute attr);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
      * Removes the attribute with the attribute id 'attrID' from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
      * the attribute set. If the attribute does not exist, ignore.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
      * @param attrID   The non-null id of the attribute to remove.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
      *                 If the attribute set ignores the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
      *                 case of its attribute ids, the case of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
      *                 attrID is ignored.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
      * @return The Attribute with the same ID as attrID that was previous
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
      *         in the attribute set;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
      *         null if no such attribute existed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
    Attribute remove(String attrID);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
      * Makes a copy of the attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
      * The new set contains the same attributes as the original set:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
      * the attributes are not themselves cloned.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
      * Changes to the copy will not affect the original and vice versa.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
      *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
      * @return A non-null copy of this attribute set.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
      */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
    Object clone();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
     * Use serialVersionUID from JNDI 1.1.1 for interoperability
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
    // static final long serialVersionUID = -7247874645443605347L;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
}