/*
 * 
 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * The contents of this file are subject to the Sun Community Source
 * License v3.0/Jini Technology Specific Attachment v 1.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://wwws.sun.com/software/jini/licensing/SCSL3_JiniTSA1.html.
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Reference Code is Jini Technology Core Platform code, v2.0. The
 * Developer of the Reference Code is Sun Microsystems, Inc.
 * 
 * Contributor(s): Sun Microsystems, Inc.
 * 
 * The contents of this file comply with the Jini Technology Core
 * Platform Compatibility Kit, v2.0A.
 * 
 * Tester(s): Sun Microsystems, Inc.
 * 
 * Test Platform(s):
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Solaris(TM)SPARC/x86
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Linux (Intel x86)
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Windows (Intel Platform)
 * 
 */

package net.jini.export;

import java.rmi.Remote;
import java.rmi.server.ExportException;

/**
 * An abstraction for exporting a single remote
 * object such that it can receive remote method invocations, and
 * later for unexporting that same remote object.
 *
 * <p>Details of the export and unexport behavior, including the
 * communication protocols used for remote invocation and additional
 * remote invocation semantics, are defined by the particular
 * implementation of this interface.
 *
 * @author	Sun Microsystems, Inc.
 * @since 2.0
 **/
public interface Exporter {

    /**
     * Exports the specified remote object and returns a proxy that can
     * be used to invoke remote methods on the exported remote object.
     * This method must only be invoked once on a given
     * <code>Exporter</code> instance.
     *
     * <p>The returned proxy implements an implementation-specific
     * set of remote interfaces of the remote object and may also implement
     * additional implementation-specific interfaces.
     *
     * <p>A remote interface is an interface that extends the interface
     * <code>java.rmi.Remote</code> and whose methods each declare at least
     * one exception whose type is <code>java.rmi.RemoteException</code>
     * or one of its superclasses.
     *
     * @param	impl a remote object to export
     * @return	a proxy for the remote object
     *
     * @throws	ExportException if a problem occurs exporting the object
     * @throws	SecurityException if a <code>SecurityException</code>
     *		occurs exporting the object
     * @throws	NullPointerException if <code>impl</code> is <code>null</code>
     * @throws	IllegalStateException if an object has already been exported
     *		with this <code>Exporter</code> instance
     **/
    public Remote export(Remote impl) throws ExportException;

    /**
     * Unexports the remote object that was exported by this
     * <code>Exporter</code> such that it will no longer receive remote
     * method invocations that were made possible as a result of exporting
     * it with this <code>Exporter</code>.  The unexport operation may
     * not occur if the <code>force</code> argument is <code>false</code>.
     * This method must only be invoked after the <code>export</code>
     * method has been invoked on this <code>Exporter</code> instance to
     * export a remote object successfully.
     *
     * <p>This method returns <code>true</code> if upon return, the remote
     * object is no longer exported with this <code>Exporter</code>, and
     * <code>false</code> if the remote object remains exported with this
     * <code>Exporter</code>.  This method will always return
     * <code>true</code> if it has returned <code>true</code> previously.
     *
     * <p>The <code>force</code> parameter serves to indicate whether or not
     * the caller desires the unexport to occur even if there are known
     * remote calls pending or in progress to the remote object that were
     * made possible by this <code>Exporter</code>:
     *
     * <ul>
     * <li>If <code>force</code> is <code>true</code>, then the remote
     * object will be forcibly unexported even if there are remote calls
     * pending or in progress, and this method will return
     * <code>true</code>.
     * 
     * <li>If <code>force</code> is <code>false</code>, then this acts as
     * a hint to the implementation that the remote object should not be
     * unexported if there are known remote calls pending or in progress,
     * and this method will either unexport the remote object and return
     * <code>true</code> or not unexport the remote object and return
     * <code>false</code>.  If the implementation detects that there are
     * indeed remote calls pending or in progress, then it should return
     * <code>false</code>; otherwise, it must return <code>true</code>.
     * If the implementation does not support being able to unexport
     * conditionally based on knowledge of remote calls pending or in
     * progress, then it must implement this method as if
     * <code>force</code> were always <code>true</code>.
     * </ul>
     *
     * <p>If the remote object is unexported as a result of this method,
     * then the implementation may (and should, if possible) prevent remote
     * calls in progress from being able to communicate their results
     * successfully.
     *
     * @param	force if <code>true</code>, the remote object will be
     * unexported even if there are remote calls pending or in progress;
     * if <code>false</code>, the remote object may only be unexported if
     * there are no known remote calls pending or in progress
     *
     * @return	<code>true</code> if the remote object is unexported when
     * this method returns and <code>false</code> otherwise
     *
     * @throws	IllegalStateException if an object has not been exported
     * with this <code>Exporter</code> instance
     **/
    public boolean unexport(boolean force);
}

