1 /*
   2  * Copyright (c) 1996, 2003, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.corba.se.impl.naming.cosnaming;
  27 
  28 // Import general CORBA classes
  29 import org.omg.CORBA.ORB;
  30 import org.omg.CORBA.Object;
  31 
  32 // Import org.omg.CosNaming classes
  33 import org.omg.CosNaming.Binding;
  34 import org.omg.CosNaming.BindingType;
  35 import org.omg.CosNaming.BindingHolder;
  36 import org.omg.CosNaming.BindingListHolder;
  37 import org.omg.CosNaming.BindingIteratorHolder;
  38 import org.omg.CosNaming.BindingIteratorPOA;
  39 import org.omg.CORBA.BAD_PARAM;
  40 
  41 /**
  42  * Class BindingIteratorImpl implements the org.omg.CosNaming::BindingIterator
  43  * interface, but does not implement the method to retrieve the next
  44  * binding in the NamingContext for which it was created. This is left
  45  * to a subclass, which is why this class is abstract; BindingIteratorImpl
  46  * provides an implementation of the interface operations on top of two
  47  * subclass methods, allowing multiple implementations of iterators that
  48  * differ in storage and access to the contents of a NamingContext
  49  * implementation.
  50  * <p>
  51  * The operation next_one() is implemented by the subclass, whereas
  52  * next_n() is implemented on top of the next_one() implementation.
  53  * Destroy must also be implemented by the subclass.
  54  * <p>
  55  * A subclass must implement NextOne() and Destroy(); these
  56  * methods are invoked from synchronized methods and need therefore
  57  * not be synchronized themselves.
  58  */
  59 public abstract class BindingIteratorImpl extends BindingIteratorPOA
  60 {
  61     protected ORB orb ;
  62 
  63     /**
  64      * Create a binding iterator servant.
  65      * runs the super constructor.
  66      * @param orb an ORB object.
  67      * @exception java.lang.Exception a Java exception.
  68      */
  69     public BindingIteratorImpl(ORB orb)
  70         throws java.lang.Exception
  71     {
  72         super();
  73         this.orb = orb ;
  74     }
  75 
  76     /**
  77      * Return the next binding. It also returns true or false, indicating
  78      * whether there were more bindings.
  79      * @param b The Binding as an out parameter.
  80      * @return true if there were more bindings.
  81      * @exception org.omg.CORBA.SystemException One of a fixed set of CORBA
  82      * system exceptions.
  83      * @see NextOne
  84      */
  85     public synchronized boolean next_one(org.omg.CosNaming.BindingHolder b)
  86     {
  87         // NextOne actually returns the next one
  88         return NextOne(b);
  89     }
  90 
  91     /**
  92      * Return the next n bindings. It also returns true or false, indicating
  93      * whether there were more bindings.
  94      * @param how_many The number of requested bindings in the BindingList.
  95      * @param blh The BindingList as an out parameter.
  96      * @return true if there were more bindings.
  97      * @exception org.omg.CORBA.SystemException One of a fixed set of CORBA
  98      * system exceptions.
  99      * @see NextOne
 100      */
 101     public synchronized boolean next_n(int how_many,
 102         org.omg.CosNaming.BindingListHolder blh)
 103     {
 104         if( how_many == 0 ) {
 105             throw new BAD_PARAM( " 'how_many' parameter is set to 0 which is" +
 106             " invalid" );
 107         }
 108         return list( how_many, blh );
 109     }
 110 
 111     /**
 112      * lists next n bindings. It returns true or false, indicating
 113      * whether there were more bindings. This method has the package private
 114      * scope, It will be called from NamingContext.list() operation or
 115      * this.next_n().
 116      * @param how_many The number of requested bindings in the BindingList.
 117      * @param blh The BindingList as an out parameter.
 118      * @return true if there were more bindings.
 119      */
 120     public boolean list( int how_many, org.omg.CosNaming.BindingListHolder blh)
 121     {
 122         // Take the smallest of what's left and what's being asked for
 123         int numberToGet = Math.min(RemainingElements(),how_many);
 124 
 125         // Create a resulting BindingList
 126         Binding[] bl = new Binding[numberToGet];
 127         BindingHolder bh = new BindingHolder();
 128         int i = 0;
 129         // Keep iterating as long as there are entries
 130         while (i < numberToGet && this.NextOne(bh) == true) {
 131             bl[i] = bh.value;
 132             i++;
 133         }
 134         // Found any at all?
 135         if (i == 0) {
 136             // No
 137             blh.value = new Binding[0];
 138             return false;
 139         }
 140 
 141         // Set into holder
 142         blh.value = bl;
 143 
 144         return true;
 145     }
 146 
 147 
 148 
 149 
 150     /**
 151      * Destroy this BindingIterator object. The object corresponding to this
 152      * object reference is destroyed.
 153      * @exception org.omg.CORBA.SystemException One of a fixed set of CORBA
 154      * system exceptions.
 155      * @see Destroy
 156      */
 157     public synchronized void destroy()
 158     {
 159         // Destroy actually destroys
 160         this.Destroy();
 161     }
 162 
 163     /**
 164      * Abstract method for returning the next binding in the NamingContext
 165      * for which this BindingIterator was created.
 166      * @param b The Binding as an out parameter.
 167      * @return true if there were more bindings.
 168      * @exception org.omg.CORBA.SystemException One of a fixed set of CORBA
 169      * system exceptions.
 170      */
 171     protected abstract boolean NextOne(org.omg.CosNaming.BindingHolder b);
 172 
 173     /**
 174      * Abstract method for destroying this BindingIterator.
 175      * @exception org.omg.CORBA.SystemException One of a fixed set of CORBA
 176      * system exceptions.
 177      */
 178     protected abstract void Destroy();
 179 
 180     /**
 181      * Abstract method for returning the remaining number of elements.
 182      * @return the remaining number of elements in the iterator.
 183      */
 184     protected abstract int RemainingElements();
 185 }