directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 10476 - incubator/directory/rms/trunk/je/src/java/org/apache/rms/je
Date Sat, 01 May 2004 07:09:26 GMT
Author: akarasulu
Date: Sat May  1 00:09:24 2004
New Revision: 10476

Added:
   incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIterator.java   (contents,
props changed)
   incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitor.java   (contents,
props changed)
   incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitorAdapter.java
  (contents, props changed)
Log:
code that makes building iterators over cursors much easier

Added: incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIterator.java
==============================================================================
--- (empty file)
+++ incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIterator.java	Sat May  1
00:09:24 2004
@@ -0,0 +1,294 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permission and
+ *   limitations under the License.
+ *
+ */
+package org.apache.rms.je ;
+
+
+import java.util.Iterator ;
+import java.util.Observable ;
+
+import com.sleepycat.je.OperationStatus ;
+
+
+/**
+ * A special JE iterator implementation that tries to cleanup cursor resources
+ * when consumed or failures result.
+ * 
+ * @author <a href="mailto:directory-dev@incubator.apache.org">Apache Directory Project</a>
+ * @version $Rev$
+ */
+public abstract class JeIterator extends Observable implements Iterator
+{
+    /** tracks if we have another item to return */
+    private boolean hasNext = true ;
+    /** the operation status of the last prefetch operation */
+    private OperationStatus status ;
+    /** the last prefetched item */
+    private Object prefetched ;
+    /** a monitor to track the events associated with this iterator */
+    private JeIteratorMonitor monitor ;
+    /** a failure if one has occurred */
+    private Throwable fault ;
+
+
+    /**
+     * Creates a JeIterator with an initial monitor adapter.
+     */
+    protected JeIterator()
+    {
+        this.monitor = new JeIteratorMonitorAdapter() ;
+    }
+
+
+    /**
+     * Remove is unsupported so calling this monitors the call, closes this
+     * iterator and throws an exception.
+     *
+     * @throws UnsupportedOperationException every time.
+     */
+    public final void remove()
+    {
+        UnsupportedOperationException fault ;
+
+        monitor.removeAttempted( this ) ;
+        fault = new UnsupportedOperationException() ;
+        close( fault ) ;
+
+        throw fault ;
+    }
+
+
+    /**
+     * Gets the boolean hasNext flag for this iterator.
+     *
+     * @return whether or not another value is available by calling next()
+     */
+    public final boolean hasNext()
+    {
+        return hasNext ;
+    }
+
+
+    /**
+     * Saves the last prefetched value which is returned but before returning
+     * it prefetches the next value.   Failures and succcesses are reported to
+     * the monitor.
+     *
+     * @return the next item in the iteration
+     */
+    public final Object next()
+    {
+        Object retval = prefetched ;
+
+        try
+        {
+            prefetched = prefetch() ;
+            monitor.prefetch( this, prefetched, retval ) ;
+        }
+        catch ( Exception e )
+        {
+            close( e ) ;
+            monitor.prefetchFailure( this, retval ) ;
+
+            if ( e instanceof RuntimeException )
+            {
+                throw ( RuntimeException ) e ;
+            }
+        }
+        catch ( Error e )
+        {
+            close( e ) ;
+            monitor.prefetchFailure( this, retval ) ;
+            throw e ;
+        }
+
+        return retval ;
+    }
+
+
+    /**
+     * Checks to see if this iterator was closed prematurely due to a failure
+     * or if it was closed by being consumed or by an intentional close call.
+     *
+     * @return true if this closed due to a failure, false otherwise
+     */
+    public final boolean hasFailed()
+    {
+        return fault != null ;
+    }
+
+
+    /**
+     * Gets the failure that prematurely closed this cursor.
+     *
+     * @return the failure that prematurely closed this cursor, or null if
+     * no failures occured during cursor operation
+     */
+    public final Throwable getFault()
+    {
+        return fault ;
+    }
+
+
+    /**
+     * Gets the status of the last prefetch operation against a JE cursor.
+     *
+     * @return the status of the last prefetch operation
+     */
+    public final OperationStatus getStatus()
+    {
+        return status ;
+    }
+
+
+    /**
+     * Sets and returns the status for call chaining - closes this iterator if
+     * status is not equal to OperationStatus.SUCCESS.
+     *
+     * @param status the status to set
+     * @return the status argument for call chaining
+     */
+    protected final OperationStatus setStatus( OperationStatus status )
+    {
+        this.status = status ;
+
+        if ( status != OperationStatus.SUCCESS )
+        {
+            close() ;
+        }
+
+        return this.status ;
+    }
+
+
+    /**
+     * Use this close method when failures cause this iterator to close
+     * prematurely, this sets the fault member of the class before a regular
+     * close call.
+     *
+     * @param fault a failure that caused this iterator to prematurely close
+     */
+    protected final void close( Throwable fault )
+    {
+        this.fault = fault ;
+        close() ;
+    }
+
+
+    /**
+     * Closes this iterator by setting hasNext flag perminantly to false and
+     * calling the cleanup method if the iterator was not closed before.
+     * Failure and success event notifications are sent via callback events
+     * to the monitor.  If any observers exist for this iterator they also are
+     * notified of the closing of this iterator.  hence
+     */
+    public final void close()
+    {
+        if ( ! hasNext )
+        {
+            return ;
+        }
+
+        hasNext = false ;
+        super.setChanged() ;
+
+        try
+        {
+            cleanup() ;
+        }
+        catch ( Exception e )
+        {
+            monitor.cleanupFailure( this, e ) ;
+            if ( e instanceof RuntimeException )
+            {
+                throw ( RuntimeException ) e ;
+            }
+        }
+        catch( Error e )
+        {
+            monitor.cleanupFailure( this, e ) ;
+            throw e ;
+        }
+
+        super.notifyObservers() ;
+        monitor.closed( this ) ;
+    }
+
+
+    /**
+     * Sets the monitor to be used by this iterator.
+     *
+     * @param monitor the monitor used for callback events
+     */
+    public final void setMonitor( JeIteratorMonitor monitor )
+    {
+        this.monitor = monitor ;
+    }
+
+
+    /**
+     * Gets the monitor for this JeIterator.
+     *
+     * @return the monitor currently in use for sending event callbacks to
+     */
+    protected JeIteratorMonitor getMonitor()
+    {
+        return this.monitor ;
+    }
+
+
+    /**
+     * Sets and returns the prefetched object.
+     *
+     * @param prefetched object that was prefetched to set
+     * @return the argument for call chaining
+     */
+    protected final Object setPrefetched( Object prefetched )
+    {
+        return this.prefetched = prefetched ;
+    }
+
+
+    /**
+     * Gets the prefetched object.
+     *
+     * @return the prefetched object or null if nothing was prefetched
+     */
+    protected final Object getPrefetched()
+    {
+        return this.prefetched ;
+    }
+
+
+    /**
+     * Concrete JeIterator's must allow for item prefetching.  This method is
+     * called usually once on initialization, and once every time next() is
+     * invoked.
+     *
+     * @return the a prefetched item from the iteration
+     * @throws Exception if there are any failures at all while prefetching
+     */
+    protected abstract Object prefetch() throws Exception ;
+
+
+    /**
+     * Concrete JeIterators must cleanup within this method which most likely
+     * means closing JE Cursors.
+     *
+     * @throws Exception if there are any failures at all while cleaning up
+     */
+    protected abstract void cleanup() throws Exception ;
+}

Added: incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitor.java
==============================================================================
--- (empty file)
+++ incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitor.java	Sat
May  1 00:09:24 2004
@@ -0,0 +1,85 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permission and
+ *   limitations under the License.
+ *
+ */
+package org.apache.rms.je ;
+
+
+/**
+ * A callback based event monitor for JeIterators.
+ * 
+ * @author <a href="mailto:directory-dev@incubator.apache.org">Apache Directory Project</a>
+ * @version $Rev$
+ */
+public interface JeIteratorMonitor
+{
+    /**
+     * Monitor callback for iterator close events.  Use the iterator's
+     * status and the hasFailed method to determine if the iterator closed
+     * because it was exhausted naturally or some failure caused it to
+     * close prematurely.
+     *
+     * @param iterator the iterator that got closed
+     */
+    void closed( JeIterator iterator ) ;
+
+    /**
+     * Monitor callback for successful prefetch events within the initializer
+     * of a JeIterator.
+     *
+     * @param iterator the iterator that prefetched an item in constructor
+     * @param prefetched the item prefetched by the iterator
+     */
+    void prefetch( JeIterator iterator, Object prefetched ) ;
+
+    /**
+     * Monitor callback for successful prefetch events within a next() call.
+     *
+     * @param iterator the iterator that prefetched an item in next() call
+     * @param prefetched the last item prefetched by the iterator
+     * @param retval the 2nd to last prefetched item to return in next() call
+     */
+    void prefetch( JeIterator iterator, Object prefetched, Object retval ) ;
+
+    /**
+     * Monitor callback for cleanup failure events.
+     *
+     * @param iterator the iterator that failed on a call to cleanup
+     * @param fault the fault that caused the failure
+     */
+    void cleanupFailure( JeIterator iterator, Throwable fault ) ;
+
+    /**
+     * Monitor callback for prefetch failure events within a next() call.
+     *
+     * @param iterator the iterator that failed on a prefetch() within next()
+     * @param retval last value successfully prefetched to return from next()
+     */
+    void prefetchFailure( JeIterator iterator, Object retval ) ;
+
+    /**
+     * Monitor callback for prefetch failure events within the constructor.
+     *
+     * @param iterator the iterator that failed to prefetch() the first time
+     */
+    void prefetchFailure( JeIterator iterator ) ;
+
+    /**
+     * Monitor callback for attempts to call remove which is unsupported.
+     *
+     * @param iterator the iterator on which remove was invoked
+     */
+    void removeAttempted( JeIterator iterator ) ;
+}

Added: incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitorAdapter.java
==============================================================================
--- (empty file)
+++ incubator/directory/rms/trunk/je/src/java/org/apache/rms/je/JeIteratorMonitorAdapter.java
Sat May  1 00:09:24 2004
@@ -0,0 +1,83 @@
+/*
+ *   Copyright 2004 The Apache Software Foundation
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permission and
+ *   limitations under the License.
+ *
+ */
+package org.apache.rms.je ;
+
+
+/**
+ * A no-op monitor adapter for JeIterators.  At a bare minimum this adapter
+ * reports any failures to stderr.  If this is not preferrable implement
+ * another monitor and set the iterator's monitor.
+ *
+ * @author <a href="mailto:directory-dev@incubator.apache.org">Apache Directory Project</a>
+ * @version $Rev$
+ */
+public class JeIteratorMonitorAdapter implements JeIteratorMonitor
+{
+    public void closed( JeIterator iterator )
+    {
+        if ( iterator.hasFailed() )
+        {
+            iterator.getFault().printStackTrace() ;
+        }
+    }
+
+
+    public void prefetch( JeIterator iterator, Object prefetched )
+    {
+    }
+
+
+    public void prefetch( JeIterator iterator, Object prefetched, Object retval )
+    {
+    }
+
+
+    public void cleanupFailure( JeIterator iterator, Throwable fault )
+    {
+        if ( iterator.hasFailed() )
+        {
+            iterator.getFault().printStackTrace() ;
+        }
+    }
+
+
+    public void prefetchFailure( JeIterator iterator, Object retval )
+    {
+        if ( iterator.hasFailed() )
+        {
+            iterator.getFault().printStackTrace() ;
+        }
+    }
+
+
+    public void prefetchFailure( JeIterator iterator )
+    {
+        if ( iterator.hasFailed() )
+        {
+            iterator.getFault().printStackTrace() ;
+        }
+    }
+
+
+    public void removeAttempted( JeIterator iterator )
+    {
+        if ( iterator.hasFailed() )
+        {
+            iterator.getFault().printStackTrace() ;
+        }
+    }
+}

Mime
View raw message