You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by ak...@apache.org on 2004/03/14 22:19:34 UTC
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
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 ) ;
+}