Delayed Unmarshalling and Codebase provisioning.

[Peter Firmstone <ji...@zeus.net.au>]

Appended below is an abstract class, that represents additional Service 
API, which a ServiceRegistrar can implement to allow a client to delay 
unmarshalling or perform codebase provisioning.

It provides a method allowing unmarshalling to be performed at a time 
that suits the client, either with a default codebase, or a codebase 
provisioned by the client.

It is intended to be backward compatible with existing ServiceRegistrar 
and ServiceDiscoveryManager clients.

To utilise delayed unmarshalling with existing client code, minor 
modifications to an existing ServiceItemFilter can effect unmarshalling 
of MarshalledServiceItem after checking Entry's, before proxy contraints 
and trust verification, it can be managed using 
ServiceDiscoveryManager.  Alternately unmarshalling can be effected by 
the client itself.

I'm not entirely sure about using a URI array for the annotation, or 
whether this should be a String, in case a URL scheme doesn't exist at 
the client.

Note that this is an abstract class, without any serial fields, so the 
serialized form of the implementation doesn't become part of the public 
API.  This will also require additional methods to be added to 
MarshalledInstance.  It may be necessary to override toString() to 
perform unmarshalling of the service, although I'm not clear on this 
point, the implementation may need to do so, rather than 
MarshalledServiceItem.

Gregg Wonderly's work on delayed unmarshalling is a precedent and 
provided the inspiration.

Does anyone have anything to contribute regarding constraints?

Thoughts?

Regards,

Peter.

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you 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.river.api.lookup;

import java.net.URI;
import java.security.CodeSource;
import net.jini.core.entry.Entry;
import net.jini.core.lookup.ServiceID;
import net.jini.core.lookup.ServiceItem;

/**
 * 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 can exclude any Entry's, however where Entry
 * classes already exist at the client, they should be unmarshalled.
 *
 * The ServiceID shall be in unmarshalled form always in the ServiceItem 
super class.
 *
 * Since the ServiceItem.service is null, use of this class in existing 
software
 * will not return the service, however it will not break that software as
 * ServiceItem's contract is to set service or Entry's to null when they 
cannot
 * be unmarshalled.
 *
 * ServiceItem's toString() method will return a different result for
 * MarshalledServiceItem instances.
 *
 * If required, a new ServiceItem that is fully unmarshalled
 * can be constructed from this class's methods and ServiceID.
 *
 * @author Peter Firmstone.
 */
public abstract class MarshalledServiceItem extends ServiceItem{
    private static final long SerialVersionUID = 1L;
    protected MarshalledServiceItem(ServiceID id, Entry[] 
unmarshalledEntries){
        super(id, (Object) null, unmarshalledEntries);
    }
    /**
     * Unmarshall the service proxy.
     * @param load service with local or existing CodeSource or null for
     * default.
     * @return the service proxy, null if class not found.
     */
    public abstract Object getService(CodeSource[] code);
    /**
     * Unmarshall the Entry's
     * @return array of Entry's, null entry in array for any class not 
found.
     */
    public abstract Entry[] getEntries();
    
    public abstract URI[] getAnnotations();
}