javax.tv.xlet.Xlet Maven / Gradle / Ivy
/*
* @(#)Xlet.java 1.20 00/08/23
*
* Copyright 1998-2000 by Sun Microsystems, Inc.,
* 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
* All rights reserved.
*
* This software is the confidential and proprietary information
* of Sun Microsystems, Inc. ("Confidential Information"). You
* shall not disclose such Confidential Information and shall use
* it only in accordance with the terms of the license agreement
* you entered into with Sun.
*/
package javax.tv.xlet;
/**
* This interface allows an application manager to create,
* initialize, start, pause, and destroy an Xlet.
* An Xlet is an application or service designed to be run and
* controlled by an application manager via this lifecycle interface.
* The lifecycle states allow the application manager to manage
* the activities of multiple Xlets within a runtime environment
* selecting which Xlets are active at a given time.
* The application manager maintains the state of the Xlet and
* invokes method on the Xlet via the lifecycle methods. The Xlet
* implements these methods to update its internal activities and
* resource usage as directed by the application manager.
* The Xlet can initiate some state changes itself and informs
* the application manager of those state changes
* by invoking methods on XletContext.
*
* In order to support interoperability between Xlets and application
* managers, all Xlet classes must provide a public no-argument
* constructor.
*
* Note: The methods on this interface are meant to signal state
* changes. The state change is not considered complete until the state
* change method has returned. It is intended that these methods return
* quickly.
*
* @see XletContext
*/
public interface Xlet {
/**
* Signals the Xlet to initialize itself and enter the
* Paused state.
* The Xlet shall initialize itself in preparation for providing service.
* It should not hold shared resources but should be prepared to provide
* service in a reasonable amount of time.
* An XletContext is used by the Xlet to access
* properties associated with its runtime environment.
* After this method returns successfully, the Xlet
* is in the Paused state and should be quiescent.
* Note: This method shall only be called once.
*
* @param ctx The XletContext of this Xlet.
* @exception XletStateChangeException If the Xlet cannot be
* initialized.
* @see javax.tv.xlet.XletContext
*/
public void initXlet(XletContext ctx) throws XletStateChangeException;
/**
* Signals the Xlet to start providing service and
* enter the Active state.
* In the Active state the Xlet may hold shared resources.
* The method will only be called when
* the Xlet is in the paused state.
*
*
* @exception XletStateChangeException is thrown if the Xlet
* cannot start providing service.
*/
/*
* Two kinds of failures can prevent the service from starting,
* transient and non-transient. For transient failures the
* XletStateChangeException exception should be thrown.
* For non-transient failures the XletContext.notifyDestroyed
* method should be called.
*
* @see XletContext#notifyDestroyed
*/
public void startXlet() throws XletStateChangeException;
/**
*
* Signals the Xlet to stop providing service and
* enter the Paused state.
* In the Paused state the Xlet must stop providing
* service, and might release all shared resources
* and become quiescent. This method will only be called
* called when the Xlet is in the Active state.
*
*/
public void pauseXlet();
/**
* Signals the Xlet to terminate and enter the Destroyed state.
* In the destroyed state the Xlet must release
* all resources and save any persistent state. This method may
* be called from the Loaded, Paused or
* Active states.
* Xlets should
* perform any operations required before being terminated, such as
* releasing resources or saving preferences or
* state.
*
* NOTE: The Xlet can request that it not enter the Destroyed
* state by throwing an XletStateChangeException. This
* is only a valid response if the unconditional
* flag is set to false. If it is true
* the Xlet is assumed to be in the Destroyed state
* regardless of how this method terminates. If it is not an
* unconditional request, the Xlet can signify that it wishes
* to stay in its current state by throwing the Exception.
* This request may be honored and the destroyXlet()
* method called again at a later time.
*
*
* @param unconditional If unconditional is true when this
* method is called, requests by the Xlet to not enter the
* destroyed state will be ignored.
*
* @exception XletStateChangeException is thrown if the Xlet
* wishes to continue to execute (Not enter the Destroyed
* state).
* This exception is ignored if unconditional
* is equal to true.
*
*
*/
public void destroyXlet(boolean unconditional)
throws XletStateChangeException;
}