001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.naming.directory;
019:
020: import java.io.Serializable;
021: import javax.naming.NamingEnumeration;
022:
023: /**
024: * This is the interface to a collection of attributes associated with a
025: * directory entry.
026: * <p>
027: * This interface defines the methods that are implemented by a collection of a
028: * particular directory entry's attributes.
029: * </p>
030: * <p>
031: * A directory entry can have zero or more attributes comprising its attributes
032: * collection. The attributes are unordered within the collection. The
033: * attributes can be identified by name. The names of attributes are either case
034: * sensitive or case insensitive as indicated by the <code>isCaseIgnored</code>
035: * method. Method names refer to attribute ID (identity) rather than name, for
036: * brevity.
037: * </p>
038: * <p>
039: * The attribute collection is created when the directory entry is created.
040: * </p>
041: */
042: public interface Attributes extends Cloneable, Serializable {
043:
044: /**
045: * Returns a deep copy of this <code>Attributes</code> instance. The
046: * attribute objects are not cloned.
047: *
048: * @return a deep copy of this <code>Attributes</code> instance
049: */
050: Object clone();
051:
052: /**
053: * Returns the attribute with the specified name (ID). The name is case
054: * insensitive if <code>isCaseIgnored()</code> is true. The return value
055: * is <code>null</code> if no match is found.
056: *
057: * @param id
058: * attribute name (ID)
059: * @return the attribute with the specified name (ID)
060: */
061: Attribute get(String id);
062:
063: /**
064: * Returns an enumeration containing the zero or more attributes in the
065: * collection. The behaviour of the enumeration is not specified if the
066: * attribute collection is changed.
067: *
068: * @return an enumeration of all contained attributes
069: *
070: */
071: NamingEnumeration<? extends javax.naming.directory.Attribute> getAll();
072:
073: /**
074: * Returns an enumeration containing the zero or more names (IDs) of the
075: * attributes in the collection. The behaviour of the enumeration is not
076: * specified if the attribute collection is changed.
077: *
078: * @return an enumeration of the IDs of all contained attributes
079: */
080: NamingEnumeration<String> getIDs();
081:
082: /**
083: * Indicates whether case is ignored in the names of the attributes.
084: *
085: * @return true if case is ignored, otherwise false
086: */
087: boolean isCaseIgnored();
088:
089: /**
090: * Places a non-null attribute in the attribute collection. If there is
091: * already an attribute with the same ID as the new attribute, the old one
092: * is removed from the collection and is returned by this method. If there
093: * was no attribute with the same ID the return value is <code>null</code>.
094: *
095: * @param attribute
096: * the attribute to be put
097: * @return the old attribute with the same ID, if exists; otherwise
098: * <code>null</code>
099: */
100: Attribute put(Attribute attribute);
101:
102: /**
103: * Places a new attribute with the supplied ID and value into the attribute
104: * collection. If there is already an attribute with the same ID, the old
105: * one is removed from the collection and is returned by this method. If
106: * there was no attribute with the same ID the return value is
107: * <code>null</code>. The case of the ID is ignored if
108: * <code>isCaseIgnored()</code> is true.
109: *
110: * This method provides a mechanism to put an attribute with a
111: * <code>null</code> value: the value of <code>obj</code> may be
112: * <code>null</code>.
113: *
114: * @param id
115: * the ID of the new attribute to be put
116: * @param obj
117: * the value of the new attribute to be put
118: * @return the old attribute with the same ID, if exists; otherwise
119: * <code>null</code>
120: */
121: Attribute put(String id, Object obj);
122:
123: /**
124: * Removes the attribute with the specified ID. The removed attribute is
125: * returned by this method. If there is no attribute with the specified ID,
126: * the return value is <code>null</code>. The case of the ID is ignored
127: * if <code>isCaseIgnored()</code> is true.
128: *
129: * @param id
130: * the ID of the attribute to be removed
131: * @return the removed attribute, if exists; otherwise <code>null</code>
132: */
133: Attribute remove(String id);
134:
135: /**
136: * Returns the number of attributes.
137: *
138: * @return the number of attributes
139: */
140: int size();
141:
142: }
|