001 /*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License"). You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 * Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 * Copyright 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.types;
028
029
030 /**
031 * This class defines a mechanism that may be used to iterate over the
032 * members of a group. It uses an interface that is similar to that
033 * of {@code java.util.Iterator}, but is specific to group membership
034 * and that provides the ability to throw an exception when attempting
035 * to retrieve the next member (e.g., if the group contains a
036 * malformed DN or references a member that doesn't exist).
037 */
038 @org.opends.server.types.PublicAPI(
039 stability=org.opends.server.types.StabilityLevel.VOLATILE,
040 mayInstantiate=false,
041 mayExtend=true,
042 mayInvoke=true)
043 public abstract class MemberList
044 {
045 /**
046 * Indicates whether the group contains any more members.
047 *
048 * @return {@code true} if the group has at least one more member,
049 * or {@code false} if not.
050 */
051 public abstract boolean hasMoreMembers();
052
053
054
055 /**
056 * Retrieves the DN of the next group member.
057 *
058 * @return The DN of the next group member, or {@code null} if
059 * there are no more members.
060 *
061 * @throws MembershipException If a problem occurs while
062 * attempting to retrieve the next
063 * member DN.
064 */
065 public DN nextMemberDN()
066 throws MembershipException
067 {
068 Entry e = nextMemberEntry();
069 if (e == null)
070 {
071 return null;
072 }
073 else
074 {
075 return e.getDN();
076 }
077 }
078
079
080
081 /**
082 * Retrieves the entry for the next group member.
083 *
084 * @return The entry for the next group member, or {@code null} if
085 * there are no more members.
086 *
087 * @throws MembershipException If a problem occurs while
088 * attempting to retrieve the next
089 * entry.
090 */
091 public abstract Entry nextMemberEntry()
092 throws MembershipException;
093
094
095
096 /**
097 * Indicates that this member list is no longer required and that
098 * the server may clean up any resources that may have been used in
099 * the course of processing. This method must be called if the
100 * caller wishes to stop iterating across the member list before the
101 * end has been reached, although it will not be necessary if the
102 * call to {@code hasMoreMembers} returns {@code false}.
103 */
104 public abstract void close();
105 }
106