Back to index...

	/*
	* Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.rmi.activation;

	import java.rmi.Remote;
	import java.rmi.RemoteException;
	import java.rmi.activation.UnknownGroupException;
	import java.rmi.activation.UnknownObjectException;

	/**
	* The <code>ActivationSystem</code> provides a means for registering
	* groups and "activatable" objects to be activated within those groups.
	* The <code>ActivationSystem</code> works closely with the
	* <code>Activator</code>, which activates objects registered via the
	* <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,
	* which obtains information about active and inactive objects,
	* and inactive groups.
	*
	* @author Ann Wollrath
	* @see Activator
	* @see ActivationMonitor
	* @since 1.2
	*/
	public interface ActivationSystem extends Remote {

	/** The port to lookup the activation system. */
	public static final int SYSTEM_PORT = 1098;

	/**
	* The <code>registerObject</code> method is used to register an
	* activation descriptor, <code>desc</code>, and obtain an
	* activation identifier for a activatable remote object. The
	* <code>ActivationSystem</code> creates an
	* <code>ActivationID</code> (a activation identifier) for the
	* object specified by the descriptor, <code>desc</code>, and
	* records, in stable storage, the activation descriptor and its
	* associated identifier for later use. When the <code>Activator</code>
	* receives an <code>activate</code> request for a specific identifier, it
	* looks up the activation descriptor (registered previously) for
	* the specified identifier and uses that information to activate
	* the object. <p>
	*
	* @param desc the object's activation descriptor
	* @return the activation id that can be used to activate the object
	* @exception ActivationException if registration fails (e.g., database
	* update failure, etc).
	* @exception UnknownGroupException if group referred to in
	* <code>desc</code> is not registered with this system
	* @exception RemoteException if remote call fails
	* @since 1.2
	*/
	public ActivationID registerObject(ActivationDesc desc)
	throws ActivationException, UnknownGroupException, RemoteException;

	/**
	* Remove the activation id and associated descriptor previously
	* registered with the <code>ActivationSystem</code>; the object
	* can no longer be activated via the object's activation id.
	*
	* @param id the object's activation id (from previous registration)
	* @exception ActivationException if unregister fails (e.g., database
	* update failure, etc).
	* @exception UnknownObjectException if object is unknown (not registered)
	* @exception RemoteException if remote call fails
	* @since 1.2
	*/
	public void unregisterObject(ActivationID id)
	throws ActivationException, UnknownObjectException, RemoteException;

	/**
	* Register the activation group. An activation group must be
	* registered with the <code>ActivationSystem</code> before objects
	* can be registered within that group.
	*
	* @param desc the group's descriptor
	* @return an identifier for the group
	* @exception ActivationException if group registration fails
	* @exception RemoteException if remote call fails
	* @since 1.2
	*/
	public ActivationGroupID registerGroup(ActivationGroupDesc desc)
	throws ActivationException, RemoteException;

	/**
	* Callback to inform activation system that group is now
	* active. This call is made internally by the
	* <code>ActivationGroup.createGroup</code> method to inform
	* the <code>ActivationSystem</code> that the group is now
	* active.
	*
	* @param id the activation group's identifier
	* @param group the group's instantiator
	* @param incarnation the group's incarnation number
	* @return monitor for activation group
	* @exception UnknownGroupException if group is not registered
	* @exception ActivationException if a group for the specified
	* <code>id</code> is already active and that group is not equal
	* to the specified <code>group</code> or that group has a different
	* <code>incarnation</code> than the specified <code>group</code>
	* @exception RemoteException if remote call fails
	* @since 1.2
	*/
	public ActivationMonitor activeGroup(ActivationGroupID id,
	ActivationInstantiator group,
	long incarnation)
	throws UnknownGroupException, ActivationException, RemoteException;

	/**
	* Remove the activation group. An activation group makes this call back
	* to inform the activator that the group should be removed (destroyed).
	* If this call completes successfully, objects can no longer be
	* registered or activated within the group. All information of the
	* group and its associated objects is removed from the system.
	*
	* @param id the activation group's identifier
	* @exception ActivationException if unregister fails (e.g., database
	* update failure, etc).
	* @exception UnknownGroupException if group is not registered
	* @exception RemoteException if remote call fails
	* @since 1.2
	*/
	public void unregisterGroup(ActivationGroupID id)
	throws ActivationException, UnknownGroupException, RemoteException;

	/**
	* Shutdown the activation system. Destroys all groups spawned by
	* the activation daemon and exits the activation daemon.
	* @exception RemoteException if failed to contact/shutdown the activation
	* daemon
	* @since 1.2
	*/
	public void shutdown() throws RemoteException;

	/**
	* Set the activation descriptor, <code>desc</code> for the object with
	* the activation identifier, <code>id</code>. The change will take
	* effect upon subsequent activation of the object.
	*
	* @param id the activation identifier for the activatable object
	* @param desc the activation descriptor for the activatable object
	* @exception UnknownGroupException the group associated with
	* <code>desc</code> is not a registered group
	* @exception UnknownObjectException the activation <code>id</code>
	* is not registered
	* @exception ActivationException for general failure (e.g., unable
	* to update log)
	* @exception RemoteException if remote call fails
	* @return the previous value of the activation descriptor
	* @see #getActivationDesc
	* @since 1.2
	*/
	public ActivationDesc setActivationDesc(ActivationID id,
	ActivationDesc desc)
	throws ActivationException, UnknownObjectException,
	UnknownGroupException, RemoteException;

	/**
	* Set the activation group descriptor, <code>desc</code> for the object
	* with the activation group identifier, <code>id</code>. The change will
	* take effect upon subsequent activation of the group.
	*
	* @param id the activation group identifier for the activation group
	* @param desc the activation group descriptor for the activation group
	* @exception UnknownGroupException the group associated with
	* <code>id</code> is not a registered group
	* @exception ActivationException for general failure (e.g., unable
	* to update log)
	* @exception RemoteException if remote call fails
	* @return the previous value of the activation group descriptor
	* @see #getActivationGroupDesc
	* @since 1.2
	*/
	public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,
	ActivationGroupDesc desc)
	throws ActivationException, UnknownGroupException, RemoteException;

	/**
	* Returns the activation descriptor, for the object with the activation
	* identifier, <code>id</code>.
	*
	* @param id the activation identifier for the activatable object
	* @exception UnknownObjectException if <code>id</code> is not registered
	* @exception ActivationException for general failure
	* @exception RemoteException if remote call fails
	* @return the activation descriptor
	* @see #setActivationDesc
	* @since 1.2
	*/
	public ActivationDesc getActivationDesc(ActivationID id)
	throws ActivationException, UnknownObjectException, RemoteException;

	/**
	* Returns the activation group descriptor, for the group
	* with the activation group identifier, <code>id</code>.
	*
	* @param id the activation group identifier for the group
	* @exception UnknownGroupException if <code>id</code> is not registered
	* @exception ActivationException for general failure
	* @exception RemoteException if remote call fails
	* @return the activation group descriptor
	* @see #setActivationGroupDesc
	* @since 1.2
	*/
	public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)
	throws ActivationException, UnknownGroupException, RemoteException;
	}

Back to index...