directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akaras...@apache.org
Subject svn commit: rev 9469 - in incubator/directory/snickers/branches/refactoring/codec-stateful: . src src/java src/java/org src/java/org/apache src/java/org/apache/commons src/java/org/apache/commons/codec src/java/org/apache/commons/codec/stateful
Date Sun, 14 Mar 2004 21:19:34 GMT
Author: akarasulu
Date: Sun Mar 14 13:19:34 2004
New Revision: 9469

Added:
   incubator/directory/snickers/branches/refactoring/codec-stateful/
   incubator/directory/snickers/branches/refactoring/codec-stateful/.classpath
   incubator/directory/snickers/branches/refactoring/codec-stateful/.project
   incubator/directory/snickers/branches/refactoring/codec-stateful/project.properties
   incubator/directory/snickers/branches/refactoring/codec-stateful/project.xml
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/CallbackHistory.java
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderCallback.java
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitor.java
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitorAdapter.java
   incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/StatefulDecoder.java
Log:
separating out some of the optional codec interfaces

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/.classpath
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/.classpath	Sun Mar 14
13:19:34 2004
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+    <classpathentry kind="src" path="src/java"/>
+    <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+    <classpathentry kind="output" path="target/classes"/>
+</classpath>

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/.project
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/.project	Sun Mar 14 13:19:34
2004
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>codec-stateful</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>org.eclipse.jdt.core.javanature</nature>
+	</natures>
+</projectDescription>

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/project.properties
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/project.properties	Sun
Mar 14 13:19:34 2004
@@ -0,0 +1,13 @@
+maven.javadoc.customtags=tag1 tag2
+
+tag1.name=todo
+tag1.description=To Do:
+tag1.enabled=true
+tag1.scope=all
+
+tag2.name=task
+tag2.description=Task:
+tag2.enabled=false
+tag2.scope=all
+
+maven.junit.fork=true

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/project.xml
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/project.xml	Sun Mar 14
13:19:34 2004
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project>
+  <extend>${basedir}/../project.xml</extend>
+  <groupId>incubator-directory</groupId>
+  <id>codec-stateful</id>
+  <version>1.0</version>
+  
+  <name>Stateful Codec API</name>
+  <package>org.apache.common.codec.stateful</package>
+  <currentVersion>SNAPSHOT</currentVersion>
+  <inceptionYear>2004</inceptionYear>
+      
+  <shortDescription>Stateful Codec API</shortDescription>
+
+  <description>
+    API for state tracking encoders and decoders.  Such codec interfaces
+    allow for the efficient processing of data as it is made available while
+    maintaining small actively processing footprints.  Of course these aspects
+    depend on the implementation as well however this API standardizes the
+    minimum set of interfaces associated with codec's that are stateful. 
+  </description>
+      
+  <dependencies>
+    <dependency>
+      <groupId>commons-codec</groupId>
+      <artifactId>commons-codec</artifactId>
+      <version>SNAPSHOT</version>
+      <url>http://jakarta.apache.org/commons/codec</url>
+    </dependency>
+  </dependencies>
+</project>
+

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/CallbackHistory.java
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/CallbackHistory.java
Sun Mar 14 13:19:34 2004
@@ -0,0 +1,127 @@
+/*
+ *   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 permissions and
+ *   limitations under the License.
+ *
+ */
+package org.apache.commons.codec.stateful ;
+
+
+import java.util.LinkedList ;
+
+
+/**
+ * A convenience callback which collects decoded objects to audit a decoder's 
+ * activity.  The callback also comes in handy when data is to be pushed 
+ * through a decoder and grabed immediately afterwords.
+ *
+ * @author <a href="mailto:directory-dev@incubator.apache.org">
+ * Apache Directory Project</a>
+ * @version $Rev$
+ */
+public class CallbackHistory implements DecoderCallback
+{
+    /** history of decoded objects in cronological order */
+    private final LinkedList history ;
+    /** the length of callback history stored */
+    private final int length ;
+    
+
+    /**
+     * Creates an auditing callback that manages a history of fixed or 
+     * indefinate length.  If the length is fixed the history effectively 
+     * becomes a FIFO structure.
+     * 
+     * @param length the maximum length of callback history to store before
+     *  dropping decoded items, a length of zero or 1 corresponds to indefinate
+     *  history 
+     */
+    public CallbackHistory( int length )
+    {
+        this.length = length ;
+        history = new LinkedList() ;
+    }
+    
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderCallback#decodeOccurred(
+     * org.apache.commons.codec.stateful.StatefulDecoder, java.lang.Object)
+     */
+    public void decodeOccurred( StatefulDecoder decoder, Object decoded )
+    {
+        if ( length > 0 )
+        {    
+            while ( history.size() >= length )
+            {
+                history.removeLast() ;
+            }
+        }
+        
+        history.addFirst( decoded ) ;
+    }
+    
+    
+    /**
+     * Gets the most recent decoded object if one exists.
+     * 
+     * @return the most recent decoded object
+     * @throws java.util.NoSuchElementException if the history is empty
+     */
+    public Object getMostRecent()
+    {
+        return history.getFirst() ;
+    }
+    
+    
+    /**
+     * Gets the oldest decoded object if one exists.
+     * 
+     * @return the oldest decoded object
+     * @throws java.util.NoSuchElementException if the history is empty
+     */
+    public Object getOldest()
+    {
+        return history.getLast() ;
+    }
+    
+    
+    /**
+     * Tests to see if the history is empty.
+     * 
+     * @return true if the history is empty, false otherwise
+     */
+    public boolean isEmpty()
+    {
+        return history.isEmpty() ;
+    }
+    
+    
+    /**
+     * Clears the history of decoded items.
+     */
+    public void clear()
+    {
+        history.clear() ;
+    }
+    
+    
+    /**
+     * Gets the number of decoded items in the callback history.
+     * 
+     * @return the number of decoded items in the callback history
+     */
+    public int size()
+    {
+        return history.size() ;
+    }
+}

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderCallback.java
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderCallback.java
Sun Mar 14 13:19:34 2004
@@ -0,0 +1,34 @@
+/*
+ *   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 permissions and
+ *   limitations under the License.
+ *
+ */
+package org.apache.commons.codec.stateful ;
+
+/**
+ * Callback interface for stateful decoder callbacks.
+ *
+ * @author <a href="mailto:commons-dev@jakarta.apache.org">Jakarta Commons</a>
+ * @version $Rev$
+ */
+public interface DecoderCallback
+{
+    /**
+     * Callback to deliver a fully decoded object.
+     * 
+     * @param decoder the stateful decoder driving the callback
+     * @param decoded the object that was decoded
+     */
+    void decodeOccurred( StatefulDecoder decoder, Object decoded ) ;
+}

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitor.java
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitor.java
Sun Mar 14 13:19:34 2004
@@ -0,0 +1,90 @@
+/*
+ *   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 permissions and
+ *   limitations under the License.
+ *
+ */
+package org.apache.commons.codec.stateful ;
+
+
+/**
+ * Monitors decoder errors.  This class borrowed some from the <code>
+ * org.xml.sax.ErrorHandler</code> interface and its documentation.
+ *
+ * @author <a href="mailto:directory-dev@incubator.apache.org">
+ * Apache Directory Project</a>
+ * @version $Rev$
+ */
+public interface DecoderMonitor
+{
+    /**
+     * Receive notification of a recoverable error.  This callback is used to
+     * denote a failure to handle a unit of data to be encoded or decoded.  The
+     * entire [en|de]codable unit is lost but the [en|de]coding operation can 
+     * still proceed.
+     * 
+     * @param decoder the decoder that had the error
+     * @param exception the error information encapsulated in an exception
+     */
+    void error( StatefulDecoder decoder, Exception exception ) ;
+    
+    /**
+     * Receive notification of a warning.  The decoder must continue to provide
+     * normal callbacks after invoking this method: it should still be possible 
+     * for the application to process the encoded data through to the end.
+     * 
+     * @param decoder the decoder that had the error
+     * @param exception the warning information encapsulated in an exception
+     */
+    void fatalError( StatefulDecoder decoder, Exception exception ) ;
+    
+    /**
+     * Receive notification of a non-recoverable error.  The application must 
+     * assume that the stream data is unusable after the decoder has invoked 
+     * this method, and should continue (if at all) only for the sake of 
+     * collecting addition error messages: in fact, decoders are free to stop 
+     * reporting any other events once this method has been invoked.
+     *  
+     * @param decoder the decoder that had the failure
+     * @param exception the warning information encapsulated in an exception
+     */
+    void warning( StatefulDecoder decoder, Exception exception ) ;
+
+    /**
+     * Monitors callbacks that deliver a fully decoded object.
+     * 
+     * @param decoder the stateful decoder driving the callback
+     * @param decoded the object that was decoded
+     */
+    void callbackOccured( StatefulDecoder decoder, DecoderCallback cb, 
+						  Object decoded ) ;
+    
+    /**
+     * Monitors changes to the callback.
+     * 
+     * @param decoder the decoder whose callback was set
+     * @param oldcb the unset old callback, or null if none was set
+     * @param newcb the newly set callback, or null if callback is cleared
+     */
+    void callbackSet( StatefulDecoder decoder, DecoderCallback oldcb, 
+					  DecoderCallback newcb ) ;
+
+    /**
+     * Monitors changes to the the monitor for the decoder.  Note that the
+     * object being called is the new monitor.
+     * 
+     * @param decoder the decoder whose monitor was set
+     * @param oldmon the old monitor or null if none was set
+     */
+    void monitorSet( StatefulDecoder decoder, DecoderMonitor oldmon ) ;
+}

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitorAdapter.java
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/DecoderMonitorAdapter.java
Sun Mar 14 13:19:34 2004
@@ -0,0 +1,87 @@
+/*
+ *   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 permissions and
+ *   limitations under the License.
+ *
+ */
+package org.apache.commons.codec.stateful ;
+
+
+/**
+ * A do nothing decoder monitor adapter.
+ *
+ * @author Apache Software Foundation
+ * @version $Rev$
+ */
+public class DecoderMonitorAdapter implements DecoderMonitor
+{
+
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#error(
+     * org.apache.commons.codec.stateful.StatefulDecoder, java.lang.Exception)
+     */
+    public void error( StatefulDecoder decoder, Exception exception )
+    {
+    }
+
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#fatalError(
+     * org.apache.commons.codec.stateful.StatefulDecoder, java.lang.Exception)
+     */
+    public void fatalError( StatefulDecoder decoder, Exception exception )
+    {
+    }
+
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#warning(
+     * org.apache.commons.codec.stateful.StatefulDecoder, java.lang.Exception)
+     */
+    public void warning( StatefulDecoder decoder, Exception exception )
+    {
+    }
+
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#callbackOccured(
+     * org.apache.commons.codec.stateful.StatefulDecoder, 
+     * org.apache.commons.codec.stateful.DecoderCallback, java.lang.Object)
+     */
+    public void callbackOccured( StatefulDecoder decoder, DecoderCallback cb,
+								 Object decoded )
+    {
+    }
+
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#callbackSet(
+     * org.apache.commons.codec.stateful.StatefulDecoder, 
+     * org.apache.commons.codec.stateful.DecoderCallback, 
+     * org.apache.commons.codec.stateful.DecoderCallback)
+     */
+    public void callbackSet( StatefulDecoder decoder, DecoderCallback oldcb,
+							 DecoderCallback newcb )
+    {
+    }
+
+    
+    /* (non-Javadoc)
+     * @see org.apache.commons.codec.stateful.DecoderMonitor#monitorSet(
+     * org.apache.commons.codec.stateful.StatefulDecoder, 
+     * org.apache.commons.codec.stateful.DecoderMonitor)
+     */
+    public void monitorSet( StatefulDecoder decoder, DecoderMonitor oldmon )
+    {
+    }
+}

Added: incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/StatefulDecoder.java
==============================================================================
--- (empty file)
+++ incubator/directory/snickers/branches/refactoring/codec-stateful/src/java/org/apache/commons/codec/stateful/StatefulDecoder.java
Sun Mar 14 13:19:34 2004
@@ -0,0 +1,60 @@
+/*
+ *   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 permissions and
+ *   limitations under the License.
+ *
+ */
+package org.apache.commons.codec.stateful ;
+
+
+import org.apache.commons.codec.DecoderException ;
+
+
+/**
+ * A statful decoder which decodes encoded data as it arrives in peices.
+ * As chunks of encoded data arrive the decoder processes each chunk of encoded
+ * data and maintains decoding state in between arrivals: it is hence stateful 
+ * and should be associated with a single channel or encoded data producer.  
+ * When an arbitrary unit of encoding, to be determined by the encoding scheme,
+ * has been decoded, a registered DecoderCallback is called.
+ *
+ * @author <a href="mailto:commons-dev@jakarta.apache.org">Jakarta Commons</a>
+ * @version $Rev$
+ */
+public interface StatefulDecoder
+{
+    /**
+     * Decodes a peice of encoded data.  The nature of this call, synchronous
+     * verses asynchonous, with respect to driving the actual decoding of the 
+     * encoded data argument is determined by an implementation.  A return from
+     * this method does not guarrantee any callbacks: zero or more callbacks 
+     * may occur during this call.
+     * 
+     * @param encode an object representing a peice of encoded data
+     */
+    void decode( Object encoded ) throws DecoderException ;
+
+    /**
+     * Sets the callback for this StatefulDecoder.
+     * 
+     * @param cb the callback to inform of a complete decode operation
+     */
+    void setCallback( DecoderCallback cb ) ;
+    
+    /**
+     * Monitors all kinds of events that occur during processing.
+     * 
+     * @param monitor to set for this StatefulDecoder
+     */
+    void setDecoderMonitor( DecoderMonitor monitor ) ;
+}

Mime
View raw message