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; }
