You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by pe...@apache.org on 2011/02/05 01:14:25 UTC
svn commit: r1067354 - in
/incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup:
LocalServiceItem.java ServiceClasspathSubItem.java
ServiceResultStreamUnmarshaller.java StreamServiceRegistrar.java
Author: peter_firmstone
Date: Sat Feb 5 00:14:25 2011
New Revision: 1067354
URL: http://svn.apache.org/viewvc?rev=1067354&view=rev
Log:
Rename LocalServiceItem (previously named MarshalledServiceItem) to ServiceClasspathSubItem, revise StreamServiceRegistrar javadoc.
Added:
incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceClasspathSubItem.java
- copied, changed from r1066768, incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/LocalServiceItem.java
Removed:
incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/LocalServiceItem.java
Modified:
incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceResultStreamUnmarshaller.java
incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/StreamServiceRegistrar.java
Copied: incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceClasspathSubItem.java (from r1066768, incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/LocalServiceItem.java)
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceClasspathSubItem.java?p2=incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceClasspathSubItem.java&p1=incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/LocalServiceItem.java&r1=1066768&r2=1067354&rev=1067354&view=diff
==============================================================================
--- incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/LocalServiceItem.java (original)
+++ incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceClasspathSubItem.java Sat Feb 5 00:14:25 2011
@@ -25,48 +25,54 @@ import net.jini.core.lookup.ServiceID;
import net.jini.core.lookup.ServiceItem;
/**
- * LocalServiceItem extends ServiceItem and can be used anywhere a
- * ServiceItem can. A LocalServiceItem implementation instance
- * is otherwise equivalent, except only local code is used for
- * resolving classes during unmarshalling or deserialization.
- *
- * Some fields in the ServiceItem may be null or fields in Entry's may be null or
- * even the service may be null.
- *
- * The ServiceID shall be in unmarshalled form always in the ServiceItem super class.
- *
- * Since the ServiceItem.service may be null, use of this class in existing software
- * may not return the service, unless it is a reflective proxy only, however it
- * must honour ServiceItem's contract and set service, Entry's or their fields
- * to null when they cannot be unmarshalled with local code.
+ * ServiceClasspathSubItem is intended for client side filtering of lookup
+ * service results prior to clients using a service, the lookup service
+ * that implements this class, implements #getServiceItem(), so clients
+ * can obtain a complete ServiceItem when required after filtering.
+ *
+ * ServiceClasspathSubItem extends ServiceItem and can be used anywhere a
+ * ServiceItem is required for querying or inspecting Entry fields that are
+ * resolvable from the local classpath. If dynamically downloaded code is
+ * required, Remote or Serializable object references are not resolved,
+ * instead, such fields are set to null to avoid codebase download.
+ *
+ * ServiceClasspathSubItem inherits all fields from ServiceItem.
+ *
+ * Some fields in ServiceClasspathSubItem may be null or fields in Entry's may
+ * be null or even the service reference may be null, these fields would be
+ * non-null in a ServiceItem that resolves classes from dynamicly downloaded
+ * code or a remote codebase.
+ *
+ * The serviceID field shall be non-null always.
*
* ServiceItem's toString() method will return a different result for
- * LocalServiceItem instances.
+ * ServiceClasspathSubItem instances.
*
- * If required, a new ServiceItem that is fully unmarshalled
- * using remote codebases when required can be obtained by calling #unmarshall().
+ * When required, a new ServiceItem that is unmarshalled
+ * using remote codebases and dynamicly downloaded code can be obtained
+ * by calling #getServiceItem().
*
* @author Peter Firmstone.
*/
-public abstract class LocalServiceItem extends ServiceItem{
+public abstract class ServiceClasspathSubItem extends ServiceItem{
private static final long SerialVersionUID = 1L;
- protected LocalServiceItem(ServiceID id, Entry[] unmarshalledEntries){
+ protected ServiceClasspathSubItem(ServiceID id, Entry[] unmarshalledEntries){
super(id, (Object) null, unmarshalledEntries);
}
/* Default constructor for serializable sub class.
*/
- protected LocalServiceItem(){
+ protected ServiceClasspathSubItem(){
super(null, null, null);
}
/**
- * Using remote and local code as required unmarshall a new ServiceItem.
- * The returned ServiceItem may have a null service
- * or Entry's , if unmarshalling is unsuccessful, however it must not
- * be an instance of this class.
+ * Using remote and local code as required getServiceItem returns a
+ * new ServiceItem.
+ *
+ * The returned ServiceItem must not be an instance of this class.
*
* @return ServiceItem, totally unmarshalled, using remote codebase resources
* in addition to any local classpath or resources.
*/
- public abstract ServiceItem unmarshall();
+ public abstract ServiceItem getServiceItem();
}
Modified: incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceResultStreamUnmarshaller.java
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceResultStreamUnmarshaller.java?rev=1067354&r1=1067353&r2=1067354&view=diff
==============================================================================
--- incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceResultStreamUnmarshaller.java (original)
+++ incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/ServiceResultStreamUnmarshaller.java Sat Feb 5 00:14:25 2011
@@ -20,18 +20,18 @@ package org.apache.river.api.lookup;
import java.io.IOException;
import java.security.CodeSource;
-import org.apache.river.api.lookup.LocalServiceItem;
+import org.apache.river.api.lookup.ServiceClasspathSubItem;
import org.apache.river.api.util.ResultStream;
import net.jini.core.lookup.*;
/**
* Add this to the ResultStream filter chain
* {@link StreamServiceRegistrar#lookup(ServiceTemplate, Class[], int)}
- * to unmarshall any LocalServiceItem's in the stream, prior to
+ * to getServiceItem any ServiceClasspathSubItem's in the stream, prior to
* proxy verification, or applying constraints.
*
* @author Peter Firmstone.
- * @see LocalServiceItem.
+ * @see ServiceClasspathSubItem.
* @see StreamServiceRegistrar
*/
public class ServiceResultStreamUnmarshaller implements ResultStream<ServiceItem> {
@@ -50,13 +50,13 @@ public class ServiceResultStreamUnmarsha
public ServiceItem get() throws IOException {
if (input == null) return null;
for(Object item = input.get(); item != null; item = input.get()) {
- if (item instanceof LocalServiceItem){
- LocalServiceItem msi = (LocalServiceItem) item;
- return msi.unmarshall();
+ if (item instanceof ServiceClasspathSubItem){
+ ServiceClasspathSubItem msi = (ServiceClasspathSubItem) item;
+ return msi.getServiceItem();
} else if (item instanceof ServiceItem) {
return (ServiceItem) item;
}
- /* If item is not an instanceof ServiceItem or LocalServiceItem
+ /* If item is not an instanceof ServiceItem or ServiceClasspathSubItem
* it is ignored and the next item in the ResultStream is retrieved.
*/
}//end item loop
Modified: incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/StreamServiceRegistrar.java
URL: http://svn.apache.org/viewvc/incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/StreamServiceRegistrar.java?rev=1067354&r1=1067353&r2=1067354&view=diff
==============================================================================
--- incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/StreamServiceRegistrar.java (original)
+++ incubator/river/jtsk/skunk/pepe/src/org/apache/river/api/lookup/StreamServiceRegistrar.java Sat Feb 5 00:14:25 2011
@@ -24,19 +24,22 @@ import net.jini.core.lookup.ServiceItem;
import org.apache.river.api.util.ResultStream;
/**
- * Defines the interface to the lookup service. The interface is not a
- * remote interface; each implementation of the lookup service exports
- * proxy objects that implement the StreamServiceRegistrar interface local to
- * the client, using an implementation-specific protocol to communicate
- * with the actual remote server. All of the proxy methods obey normal
- * RMI remote interface semantics except where explicitly noted. Two
- * proxy objects are equal if they are proxies for the same lookup service.
- * Every method invocation (on both StreamServiceRegistrar and ServiceRegistration)
- * is atomic with respect to other invocations.
+ * Defines an extension interface to the lookup service, for use on large or
+ * global networks such as the internet or low bandwidth networks.
+ * The interface is not a remote interface; each implementation of the
+ * lookup service exports proxy objects that implement the
+ * StreamServiceRegistrar interface local to the client, using an
+ * implementation-specific protocol to communicate with the actual remote
+ * server. All of the proxy methods obey normal RMI remote interface
+ * semantics except where explicitly noted. Two proxy objects are equal if
+ * they are proxies for the same lookup service. Every method invocation
+ * (on both StreamServiceRegistrar and ServiceRegistration) is atomic with
+ * respect to other invocations.
*
* The StreamServiceRegistrar is intended to perform the same function
* as the ServiceRegistrar, but with the ability to return results as a
- * stream, so memory consumption can be minimised at the client.
+ * stream, so memory consumption is minimised at the client and network
+ * communication is minimised between the client and lookup service server.
*
* All clients utilising ServiceRegistrar, should switch to the
* StreamServiceRegistrar.
@@ -50,42 +53,31 @@ import org.apache.river.api.util.ResultS
public interface StreamServiceRegistrar extends ServiceRegistrar{
/**
- * Returns a ResultStream that provides access to MarshalledServiceItem
+ * Returns a ResultStream that provides access to ServiceClasspathSubItem
* instances. The ResultStream terminates with a null value. The result
- * stream may be infinite.
+ * stream may be infinite, or limited by an integer limit value.
*
- * MarshalledServiceItem extends ServiceItem and can be used anywhere a
- * ServiceItem can. A MarshalledServiceItem implementation instance
- * contains the marshalled form of a Service and it's Entry's,
- * the corresponding superclass ServiceItem however contains null values
- * for the service and excludes any Entry's that are not specifically requested
- * unmarshalled by this method. The ServiceID will be unmarshalled always.
- *
- * This method is designed to allow the caller to control exactly what
- * is unmarshalled and when, it allows unmarshalling of specific entries
- * that the caller may wish to utilise for filtering. It is
- * designed to allow both the caller and the implementer to deal with very
- * large result sets in an incremental fashion.
- *
- * It is absolutely essential that the caller closes and deletes any references to
- * the returned result stream as soon as it is no longer requried.
+ * A ServiceClasspathSubItem implementation instance is a ServiceItem that
+ * contains only Objects that are resolvable on the local classpath,
+ * this is useful for clients to perform filtering before requiring a
+ * download of the actual ServiceItem.
*
* @param tmpl template to match
* specified template
- * @param unmarshalledEntries only Entry's with these classes will be in
- * unmarshalled form.
- * @param maxBatchSize Allows the caller to limit the number of results
- * held locally, larger batch sizes reduce network traffic, but may delay
- * processing locally depending on implementation.
+ *
+ * @param maxBatchSize held locally, larger batch sizes reduce network
+ * traffic, but may delay processing locally depending on implementation.
+ * @param limit - Zero for infinite, otherwise limits the number of matching
+ * results.
* @return ResultStream containing ServiceItem's
- * @throws java.rmi.RemoteException
- * @see MarshalledServiceItem
+ * @throws java.io.IOException
* @see ServiceItem
+ * @see ServiceClasspathSubItem
* @see ResultStream
* @see ServiceResultStreamFilter
* @see ResultStreamUnmarshaller
* @since 2.2.0
*/
- ResultStream lookup(ServiceTemplate tmpl,
- Class[] unmarshalledEntries, int maxBatchSize) throws IOException;
+ ResultStream lookup(ServiceTemplate tmpl, int maxBatchSize, int limit)
+ throws IOException;
}