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 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
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 * docs/licenses/cddl.txt.  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 2017-2021 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.common.types;
028
029
030
031import java.io.Closeable;
032
033import com.unboundid.ldap.sdk.DN;
034import com.unboundid.util.NotExtensible;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038
039
040/**
041 * This interface defines a set of methods that may be used to iterate through
042 * the members of a group.  The {@link #close()} method should be called if the
043 * caller wants to stop iterating before reaching the end of the set of members.
044 */
045@NotExtensible()
046@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE)
047public interface GroupMemberIterator
048       extends Closeable
049{
050  /**
051   * Retrieves the DN of the entry for the next group member.  This method will
052   * not necessarily ensure that the DN refers to an entry that exists.
053   *
054   * @return  The DN of the next group member, or {@code null} if there are no
055   *          more members.
056   *
057   * @throws  GroupMemberIteratorException  If a problem is encountered while
058   *               attempting to retrieve the DN for the next member.  The
059   *               {@link GroupMemberIteratorException#mayContinueIterating()}
060   *               method should be used to determine whether the problem is
061   *               with the next member and it is safe to continue using this
062   *               iterator, or whether the iterator itself is no longer valid.
063   */
064  DN nextMemberDN()
065     throws GroupMemberIteratorException;
066
067
068
069  /**
070   * Retrieves the entry for the next group member.
071   *
072   * @return  The entry for the next group member, or {@code null} if there are
073   *          no more members.
074   *
075   * @throws  GroupMemberIteratorException  If a problem is encountered while
076   *               attempting to retrieve the entry for the next member.  The
077   *               {@link GroupMemberIteratorException#mayContinueIterating()}
078   *               method should be used to determine whether the problem is
079   *               with the next member and it is safe to continue using this
080   *               iterator, or whether the iterator itself is no longer valid.
081   */
082  Entry nextMemberEntry()
083        throws GroupMemberIteratorException;
084
085
086
087  /**
088   * Closes this iterator and indicates that the server may clean up any
089   * resources associated with it.  This method must be used if the caller
090   * wishes to stop iterating through the list of members before the end has
091   * been reached.  It may also be called after reaching the end of the member
092   * list with no ill effects, but that is not necessary.  It may also be called
093   * multiple times for the same iterator with no ill effects.
094   */
095  @Override()
096  void close();
097}