notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

svn commit: r1895 - in development/laboratory/planet/components/space: . api api/src/main/net/dpml/space impl impl/src/main/net/dpml/space/impl

From: niclas AT netcompartner.com
To: notify-dpml AT lists.ibiblio.org
Subject: svn commit: r1895 - in development/laboratory/planet/components/space: . api api/src/main/net/dpml/space impl impl/src/main/net/dpml/space/impl
Date: Thu, 24 Feb 2005 13:13:20 +0100

Author: niclas
Date: Thu Feb 24 13:13:20 2005
New Revision: 1895

Modified:
development/laboratory/planet/components/space/api/build.xml

development/laboratory/planet/components/space/api/src/main/net/dpml/space/Space.java

development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceException.java

development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceListener.java

development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceStore.java
development/laboratory/planet/components/space/impl/build.xml

development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/DefaultExpiry.java

development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeaseCallback.java

development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeasedReference.java

development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/SpaceImpl.java

development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/TransientStore.java
development/laboratory/planet/components/space/index.xml
Log:
Some more Javadocs, and cleanups.

Modified: development/laboratory/planet/components/space/api/build.xml
==============================================================================
--- development/laboratory/planet/components/space/api/build.xml
(original)
+++ development/laboratory/planet/components/space/api/build.xml Thu
Feb 24 13:13:20 2005
@@ -17,7 +17,7 @@
limitations under the License.
-->

-<project name="jpos-space-api" default="install" basedir="."
+<project name="dpml-space-api" default="install" basedir="."
xmlns:transit="antlib:net.dpml.transit"
>

Modified:
development/laboratory/planet/components/space/api/src/main/net/dpml/space/Space.java
==============================================================================
---
development/laboratory/planet/components/space/api/src/main/net/dpml/space/Space.java
(original)
+++
development/laboratory/planet/components/space/api/src/main/net/dpml/space/Space.java
Thu Feb 24 13:13:20 2005
@@ -22,19 +22,21 @@
import java.util.Iterator;

/** The Space API.
- * Space uses concepts described in the Linda Coordination Language
- * that eases the implementation of other components (such as
- * Channels, Muxes, etc.). The Space API is fairly generic, but the
- * implementations are lacking proper transaction support, and will not
- * work outside the JVM, without it.
+ * 
+ * Space uses concepts described in the Linda Coordination Language
+ * that eases the implementation of other components (such as
+ * Channels, Muxes, etc.). The Space API is fairly generic, but the
+ * implementations are lacking proper transaction support, and will not
+ * work outside the JVM, without it.
+ * 
*
- * DPML's Space is basically a Map where each entry is a LinkedList
- * of values that can be used as a BlockingQueue
+ * 
+ * DPML's default Space implementation is basically a Map where each entry
+ * is a LinkedList of values that can be used as a BlockingQueue.
+ * 
*
- * @author Alejandro Revilla
- * @author Niclas Hedhman
* @version $Id$
- * @since 2.0
+ * @since 1.0
*
* @metro.service type="net.dpml.space.Space" version="1.0"
*/
@@ -59,13 +61,21 @@
* exist in the Space before automatically discarded.
* If timeout <= 0 then it will reside there forever, and that
* is not recommended.
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to add to the Space.
*/
void place( Object key, Object value, long timeout );

/**
* Take an entry from the space, waiting forever until one exists.
* @param key Entry's key
- * @return value
+ * @return the oldest value that was associated with the key. Since
+ * this method will block until a value is available, null
+ * can never be returned.
+ * @exception InterruptedException if the thread is interrupted while
+ * waiting for a value to be available.
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to take from the Space.
*/
Object take( Object key );

@@ -76,6 +86,8 @@
* @param timeout milliseconds to wait. If zero, then don't wait at
* all, and if less < 0, wait forever.
* @return value or null
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to take from the Space.
*/
Object take( Object key, long timeout );

@@ -86,16 +98,27 @@
* @param timeout milliseconds to wait. If zero, then don't wait at
* all, and if less < 0, wait forever.
* @return value or null
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to look into the Space.
*/
Object look( Object key, long timeout );

/** Adds a SpaceListener.
- * @param key Entry's key.
+ * If the argument is null, it is silently ignored. If the listener
+ * has already been added, it will be added again, and receive duplicate
+ * notifications.
+ * @param listener the listener interested in changes to the Space.
+ * @exception SecurityException if not permitted to listen to the Space.
*/
void addSpaceListener( SpaceListener listener );

/** Removes a SpaceListener.
- * @param key Entry's key
+ * If the argument is null, it is silently ignored. If the listener has
+ * previously not been added, the method returns silently.
+ *
+ * @param listener the listener interested in changes to the Space.
+ * @exception SecurityException if not permitted to remove listeners from
+ * the Space.
*/
void removeSpaceListener( SpaceListener listener );

@@ -103,7 +126,8 @@
* at the Space.
* @return A iterator that is thread-safe and will not
* throw any <code>java.util.ConcurrentModificationExceptions</code>.
+ * @exception SecurityException if not permitted to view listeners in the
+ * Space.
*/
Iterator getSpaceListeners();
}
-

Modified:
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceException.java
==============================================================================
---
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceException.java
(original)
+++
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceException.java
Thu Feb 24 13:13:20 2005
@@ -25,9 +25,8 @@
* are wrapped around this unchecked SpaceException that we recommend to
* catch.
*
- * @author Alejandro Revilla
* @version $Id$
- * @since 2.0
+ * @since 1.0
*/
public class SpaceException extends RuntimeException
{

Modified:
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceListener.java
==============================================================================
---
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceListener.java
(original)
+++
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceListener.java
Thu Feb 24 13:13:20 2005
@@ -19,12 +19,21 @@

package net.dpml.space;

-/**
- * @author Alejandro Revilla
- * @author Niclas Hedhman
+/** The SpaceListener is interested in being notified when there are
+ * changes to the Space.
+ * 
+ * The only two changes that can appear in a Space is that entries can be
+ * added or removed. Since the entries has a limited lifetime in the Space,
+ * they can either be removed by someone taking the entry away, or if
+ * the Space times out the entry and remove it automatically. And all three
+ * of these events are reported over the SpaceListener interface.
+ * 
+ * 
+ * The Space implementation must support many
SpaceListeners.
+ * 
+ *
* @version $Id$
- * @since 2.0
- * @see net.dpml.space.Space
+ * @since 1.0
*/
public interface SpaceListener
{

Modified:
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceStore.java
==============================================================================
---
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceStore.java
(original)
+++
development/laboratory/planet/components/space/api/src/main/net/dpml/space/SpaceStore.java
Thu Feb 24 13:13:20 2005
@@ -1,5 +1,4 @@
/*
- * Copyright 2000-2005, Alejandro Revilla
* Copyright 2005, Niclas Hedhman
*
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,6 +20,18 @@

import java.util.Iterator;

+/** The SpaceStore interface defines the backend store for the space
+ * implementation to place the data in.
+ * 
+ * SpaceStore implementations does not have to be thread-safe, as
+ * this should be handled by the Space itself.
+ * 
+ *
+ * @version $Id$
+ * @since 1.0
+ *
+ * @metro.service type="net.dpml.space.SpaceStore"
+ */
public interface SpaceStore
{
/** Stores a key/value pair to the store.

Modified: development/laboratory/planet/components/space/impl/build.xml
==============================================================================
--- development/laboratory/planet/components/space/impl/build.xml
(original)
+++ development/laboratory/planet/components/space/impl/build.xml Thu
Feb 24 13:13:20 2005
@@ -17,7 +17,7 @@
limitations under the License.
-->

-<project name="jpos-space-impl" default="install" basedir="."
+<project name="dpml-space-impl" default="install" basedir="."
xmlns:x="plugin:dpml/magic/dpml-magic-core"
xmlns:transit="antlib:net.dpml.transit"
>
@@ -28,6 +28,7 @@
<x:block name="tiny-space">
<x:service type="net.dpml.space.Space" source="space-impl" />
<x:component name="space-impl" class="net.dpml.space.impl.SpaceImpl" />
+ <x:component name="transient-store"
class="net.dpml.space.impl.TransientStore" />
</x:block>
</target>

Modified:
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/DefaultExpiry.java
==============================================================================
---
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/DefaultExpiry.java
(original)
+++
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/DefaultExpiry.java
Thu Feb 24 13:13:20 2005
@@ -26,6 +26,9 @@

/** This class receives notifications from LeasedReference that expiry has
* occurred and clean up should take place.
+ *
+ * @version $Id$
+ * @since 1.0
*/
class DefaultExpiry
implements LeaseCallback

Modified:
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeaseCallback.java
==============================================================================
---
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeaseCallback.java
(original)
+++
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeaseCallback.java
Thu Feb 24 13:13:20 2005
@@ -21,10 +21,10 @@
import java.util.Timer;
import java.util.TimerTask;

-/**
- * @author Niclas Hedhman
+/** The LeaseCallback will be called when the LeasedReference expires.
+ *
* @version $Id$
- * @since 2.0
+ * @since 1.0
*/
public interface LeaseCallback
{

Modified:
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeasedReference.java
==============================================================================
---
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeasedReference.java
(original)
+++
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/LeasedReference.java
Thu Feb 24 13:13:20 2005
@@ -23,11 +23,10 @@

/**
* A facade of an object, allowing for a callback method to be called
- * when the object 'expires'.
+ * when the reference to an object 'expires'.
*
- * @author Niclas Hedhman
* @version $Id$
- * @since 2.0
+ * @since 1.0
*/
public class LeasedReference extends TimerTask
{

Modified:
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/SpaceImpl.java
==============================================================================
---
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/SpaceImpl.java
(original)
+++
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/SpaceImpl.java
Thu Feb 24 13:13:20 2005
@@ -24,6 +24,10 @@

import java.io.Serializable;

+import net.dpml.activity.Disposable;
+
+import net.dpml.lang.NullArgumentException;
+
import net.dpml.logging.Logger;

import net.dpml.service.ServiceException;
@@ -34,36 +38,95 @@
import net.dpml.space.SpaceStore;

/**
- * Tiny Space implementation
+ * Default Space implementation.
+ *
+ * This Space implementation does not implement the Security checks yet.
*
* @version $Id$
- * @since 2.0
+ * @since 1.0
*
* @metro.component name="tiny-space" lifestyle="singleton"
* @metro.service type="net.dpml.space.Space"
*/
public final class SpaceImpl
- implements Space, Serializable
+ implements Space, Serializable, Disposable
{
+ /** The store for the Space. */
private SpaceStore m_store;
+
+ /** A logger for the Space. */
private Logger m_logger;
+
+ /** The SpaceListeners of the Space. */
private LinkedList m_listeners;

+ /** The ServiceManager instance.
+ * Needed for clean-up operation.
+ */
+ private ServiceManager m_serviceManager;

/**
* @metro.logger name="space.tiny"
*
* @metro.dependency type="net.dpml.space.SpaceStore" key="store"
+ * @exception NullArgumentException if the container is unable (internal
+ * error) of providing a logger or a servicemanager instance.
*/
- public SpaceImpl( Logger logger, ServiceManager man )
- throws ServiceException
+ public SpaceImpl( Logger logger, ServiceManager servicemanager )
+ throws ServiceException, NullArgumentException
{
+ if( logger == null )
+ {
+ throw new NullArgumentException( "logger" );
+ }
+ if( servicemanager == null )
+ {
+ throw new NullArgumentException( "servicemanager" );
+ }
m_logger = logger;
- m_store = (SpaceStore) man.lookup( "store" );
+ m_serviceManager = servicemanager;
+ m_store = (SpaceStore) servicemanager.lookup( "store" );
+ }
+
+ /** Disposable implementation
+ * 
+ * Called by the container to let the Space clean up its resoruces.
+ * 
+ */
+ public void dispose()
+ {
+ m_serviceManager.release( m_store );
}

+ /**
+ * Write a new entry into the Space.
+ * 
+ * The key/value pair will be placed into the Space, and queued (fifo)
with
+ * other entries of the same key.
+ * 
+ * 
+ * The <code>timeout</code> parameter defines the minimum time that the
+ * key/value pair resides in the Space before the Space automatically
+ * removes it. Entries that are timing out will be reported over the
+ * SpaceListener interface, for interested parties.
+ * 
+ *
+ * @param key Entry's key
+ * @param value Object value
+ * @param timeout the time that the key/value pair will
+ * exist in the Space before automatically discarded.
+ * If timeout <= 0 then it will reside there forever, and that
+ * is not recommended.
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to add to the Space.
+ */
public void place( Object key, Object value, long timeout )
+ throws NullArgumentException
{
+ if( key == null )
+ {
+ throw new NullArgumentException( "key" );
+ }
LeaseCallback callback = new DefaultExpiry( this, m_logger );
key = new LeasedReference( key, callback, timeout );
Iterator listeners = null;
@@ -88,13 +151,40 @@
}
}

+ /**
+ * Take an entry from the space, waiting forever until one exists.
+ * @param key Entry's key
+ * @return the oldest value that was associated with the key. Since
+ * this method will block until a value is available, null
+ * can never be returned.
+ * @exception InterruptedException if the thread is interrupted while
+ * waiting for a value to be available.
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to take from the Space.
+ */
public Object take( Object key )
+ throws NullArgumentException
{
return take( key, -1 );
}

+ /**
+ * Take an entry from the space, waiting a limited amount of time
+ * until one exists.
+ * @param key Entry's key
+ * @param timeout milliseconds to wait. If zero, then don't wait at
+ * all, and if less < 0, wait forever.
+ * @return value or null
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to take from the Space.
+ */
public Object take( Object key, long timeout )
+ throws NullArgumentException
{
+ if( key == null )
+ {
+ throw new NullArgumentException( "key" );
+ }
Object obj = null;
synchronized( this )
{
@@ -116,8 +206,23 @@
return obj;
}

+ /**
+ * Read an entry from the space, waiting a limited amount of time
+ * until one exists.
+ * @param key Entry's key
+ * @param timeout milliseconds to wait. If zero, then don't wait at
+ * all, and if less < 0, wait forever.
+ * @return value or null
+ * @exception NullArgumentException if key is null.
+ * @exception SecurityException if not permitted to look into the Space.
+ */
public Object look( Object key, long timeout )
+ throws NullArgumentException
{
+ if( key == null )
+ {
+ throw new NullArgumentException( "key" );
+ }
synchronized( this )
{
Object obj = probe( key );
@@ -141,6 +246,13 @@
}
}

+ /** Adds a SpaceListener.
+ * If the argument is null, it is silently ignored. If the listener
+ * has already been added, it will be added again, and receive duplicate
+ * notifications.
+ * @param listener the listener interested in changes to the Space.
+ * @exception SecurityException if not permitted to listen to the Space.
+ */
public void addSpaceListener( SpaceListener listener )
{
synchronized( this )
@@ -151,6 +263,14 @@
}
}

+ /** Removes a SpaceListener.
+ * If the argument is null, it is silently ignored. If the listener has
+ * previously not been added, the method returns silently.
+ *
+ * @param listener the listener interested in changes to the Space.
+ * @exception SecurityException if not permitted to remove listeners from
+ * the Space.
+ */
public void removeSpaceListener( SpaceListener listener )
{
synchronized( this )
@@ -168,6 +288,13 @@
}
}

+ /** Returns an iterator of the SpaceListeners that has been registered
+ * at the Space.
+ * @return A iterator that is thread-safe and will not
+ * throw any <code>java.util.ConcurrentModificationExceptions</code>.
+ * @exception SecurityException if not permitted to view listeners in the
+ * Space.
+ */
public Iterator getSpaceListeners()
{
synchronized( this )
@@ -176,6 +303,11 @@
}
}

+ /** Recalls a value from the Store.
+ * @param key the key the value is stored to.
+ * @return the oldest value associated with the key, or null if no
+ * value can be found.
+ */
private Object probe( Object key )
{
Object obj = m_store.recall( key );

Modified:
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/TransientStore.java
==============================================================================
---
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/TransientStore.java
(original)
+++
development/laboratory/planet/components/space/impl/src/main/net/dpml/space/impl/TransientStore.java
Thu Feb 24 13:13:20 2005
@@ -1,5 +1,4 @@
/*
- * Copyright 2000-2005, Alejandro Revilla
* Copyright 2005, Niclas Hedhman
*
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,15 +22,23 @@
import java.util.Iterator;
import java.util.LinkedList;

+import net.dpml.lang.NullArgumentException;
+
import net.dpml.logging.Logger;

import net.dpml.space.SpaceListener;
import net.dpml.space.SpaceStore;

-/**
- * @author Niclas Hedhman
+/** This SpaceStore implementation is only backed by a HashMap, and will
+ * not keep any entries in case of JVM restart.
+ * 
+ * SpaceStore implementations does not have to be thread-safe, as
+ * this should be handled by the Space itself. This implementation IS NOT
+ * thread-safe, and therefor have a 'transient' Metro lifestyle.
+ * 
+ *
* @version $Id$
- * @since 2.0
+ * @since 1.0
*
* @metro.component name="transient-store" lifestyle="transient"
* @metro.service type="net.dpml.space.SpaceStore"

Modified: development/laboratory/planet/components/space/index.xml
==============================================================================
--- development/laboratory/planet/components/space/index.xml (original)
+++ development/laboratory/planet/components/space/index.xml Thu Feb 24
13:13:20 2005
@@ -30,8 +30,8 @@

<project basedir="api" >
<info>
- <name>jpos-space-api</name>
- <group>jpos/space</group>
+ <name>dpml-space-api</name>
+ <group>dpml/space</group>
<version>1.0</version>
</info>
<plugins>
@@ -41,16 +41,17 @@

<project basedir="impl" >
<info>
- <name>jpos-space-impl</name>
- <group>jpos/space</group>
+ <name>dpml-space-impl</name>
+ <group>dpml/space</group>
<version>1.0.0</version>
</info>
<dependencies>
- <include key="jpos-space-api" />
+ <include key="dpml-activity-api" />
<include key="dpml-logging-api" />
<include key="dpml-context-api" />
<include key="dpml-parameters-api"/>
<include key="dpml-service-api" />
+ <include key="dpml-space-api" />
</dependencies>
<plugins>
<include key="dpml-meta-tools" />

svn commit: r1895 - in development/laboratory/planet/components/space: . api api/src/main/net/dpml/space impl impl/src/main/net/dpml/space/impl, niclas, 02/24/2005