sjero.net Git - linphone/blob - p2pproxy/dependencies-src/jxse-src-2.5/api/src/net/jxta/platform/Module.java

   1 /*
   2  * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
   3  *
   4  *  The Sun Project JXTA(TM) Software License
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are met:
   8  *
   9  *  1. Redistributions of source code must retain the above copyright notice,
  10  *     this list of conditions and the following disclaimer.
  11  *
  12  *  2. Redistributions in binary form must reproduce the above copyright notice,
  13  *     this list of conditions and the following disclaimer in the documentation
  14  *     and/or other materials provided with the distribution.
  15  *
  16  *  3. The end-user documentation included with the redistribution, if any, must
  17  *     include the following acknowledgment: "This product includes software
  18  *     developed by Sun Microsystems, Inc. for JXTA(TM) technology."
  19  *     Alternately, this acknowledgment may appear in the software itself, if
  20  *     and wherever such third-party acknowledgments normally appear.
  21  *
  22  *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
  23  *     not be used to endorse or promote products derived from this software
  24  *     without prior written permission. For written permission, please contact
  25  *     Project JXTA at http://www.jxta.org.
  26  *
  27  *  5. Products derived from this software may not be called "JXTA", nor may
  28  *     "JXTA" appear in their name, without prior written permission of Sun.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
  31  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  32  *  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
  33  *  MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  34  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  36  *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  37  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  38  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  39  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  *
  41  *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United
  42  *  States and other countries.
  43  *
  44  *  Please see the license information page at :
  45  *  <http://www.jxta.org/project/www/license.html> for instructions on use of
  46  *  the license in source files.
  47  *
  48  *  ====================================================================
  49  *
  50  *  This software consists of voluntary contributions made by many individuals
  51  *  on behalf of Project JXTA. For more information on Project JXTA, please see
  52  *  http://www.jxta.org.
  53  *
  54  *  This license is based on the BSD license adopted by the Apache Foundation.
  55  */
  56
  57 package net.jxta.platform;
  58
  59
  60 import net.jxta.peergroup.PeerGroup;
  61 import net.jxta.document.Advertisement;
  62 import net.jxta.id.ID;
  63 import net.jxta.exception.PeerGroupException;
  64
  65
  66 /**
  67  * Defines the interface for modules loaded by PeerGroups. Message transports,
  68  * services and applications need to implement this interface if they are
  69  * to be loaded and started by a PeerGroup. Service and Application extend
  70  * Module, PeerGroup implements Service and ShellApp implements Application, as
  71  * a result both implement Module.
  72  *
  73  * <p/>Jxta Modules are given their initialization parameters via the init()
  74  * method rather than a non-default constructor.
  75  *
  76  * <p/>Modules are passed the peer group within which they are created.
  77  * From the peergroup object, Modules can access all the peer group
  78  * services. The PeerGroup within which a PeerGroup runs is known as its
  79  * parent.
  80  *
  81  * <p/>The initial root peer group is known as the World Peer Group and is
  82  * implemented by an object of class Platform, a subclass of PeerGroup.
  83  * The "parent" PeerGroup of the World Peer Group is null.
  84  *
  85  * @see net.jxta.protocol.ModuleImplAdvertisement
  86  * @see net.jxta.platform.ModuleClassID
  87  * @see net.jxta.peergroup.PeerGroup
  88  * @see net.jxta.document.Advertisement
  89  * @see net.jxta.id.ID
  90  * @see net.jxta.platform.Application
  91  * @see net.jxta.service.Service
  92  **/
  93 public interface Module {
  94
  95     /**
  96      * <code>startApp()</code> completed successfully. This module claims to now
  97      * be fully functional and no further invocation of startApp is required.
  98      **/
  99     public static final int START_OK = 0;
 100
 101     /**
 102      * This is to be used mostly by co-dependent services when started as
 103      * a set (such as {@link PeerGroup} services) so that their
 104      * <code>startApp()</code> method may be invoked multiple times.
 105      *
 106      * <p/>This value indicates that startApp must be retried later in order for
 107      * this module to become fully functional. However, some progress in
 108      * functionality was accomplished.
 109      *
 110      * <p/>This is a strong indication that some other modules may be able
 111      * to advance or complete their initialization if their
 112      * <code>startApp()</code> method is invoked again.
 113      *
 114      * <p/>The distinction between START_AGAIN_STALLED and START_AGAIN_PROGRESS
 115      * is only a hint. Each module makes an arbitrary judgment in this
 116      * respect. It is up to the invoker of startApp to ensure that the
 117      * starting of a set of modules eventually succeeds or fails.
 118      **/
 119     public static final int START_AGAIN_PROGRESS = 1;
 120
 121     /**
 122      * This is to be used mostly by co-dependent services when started as
 123      * a set (such as {@link PeerGroup} services) so that their startApp
 124      * method may be invoked multiple times.
 125      *
 126      * <p/>This value indicates that startApp must be retried later in order for
 127      * this module to become fully functional. However, some progress in
 128      * functionality was accomplished.
 129      *
 130      * <p/>If all modules in a set return this value, it is a strong indication
 131      * that the modules co-dependency is such that it prevents them
 132      * collectively from starting.
 133      *
 134      * <p/>The distinction between START_AGAIN_STALLED and START_AGAIN_PROGRESS
 135      * is only a hint. Each module makes an arbitrary judgment in this
 136      * respect. It is up to the invoker of startApp to ensure that the
 137      * starting of a set of modules eventually succeeds or fails.
 138      **/
 139     public static final int START_AGAIN_STALLED = 2;
 140
 141     /**
 142      * This return result is used to indicate that the module refuses to start
 143      * because it has been configured to be disabled or otherwise cannot run
 144      * (missing hardware, missing system resources, etc.) The module will not be
 145      * functional and should be discarded but the failure to load may be ignored
 146      * by the loader at it's discretion.
 147      */
 148     public static final int START_DISABLED = Integer.MIN_VALUE + 100;
 149
 150     /**
 151      * Initialize the module, passing it its peer group and advertisement.
 152      *
 153      * <p/>Note: when subclassing one of the existing PeerGroup implementations
 154      * (which implement Module), it may not be recommended to overload the init
 155      * method. See the documentation of the PeerGroup class being subclassed.
 156      *
 157      *  @param group The PeerGroup from which this Module can obtain services.
 158      *  If this module is a Service, this is also the PeerGroup of which this
 159      *  module is a service.
 160      *
 161      *  @param assignedID Identity of Module within group.
 162      *  modules can use it as a the root of their namespace to create
 163      *  names that are unique within the group but predictable by the
 164      *  same module on another peer. This is normally the ModuleClassID
 165      *  which is also the name under which the module is known by other
 166      *  modules. For a group it is the PeerGroupID itself.
 167      *  The parameters of a service, in the Peer configuration, are indexed
 168      *  by the assignedID of that service, and a Service must publish its
 169      *  run-time parameters in the Peer Advertisement under its assigned ID.
 170      *
 171      *  @param implAdv The implementation advertisement for this
 172      *  Module. It is permissible to pass null if no implementation
 173      *  advertisement is available. This may happen if the
 174      *  implementation was selected by explicit class name rather than
 175      *  by following an implementation advertisement. Modules are not
 176      *  required to support that style of loading, but if they do, then
 177      *  their documentation should mention it.
 178      *
 179      *  @exception PeerGroupException This module failed to initialize.
 180      **/
 181     public void init(PeerGroup group, ID assignedID, Advertisement implAdv) throws PeerGroupException;
 182
 183     /**
 184      * Complete any remaining initialization of the module. The module should
 185      * be fully functional after <code>startApp()</code> is completed. That is
 186      * also the opportunity to supply arbitrary arguments (mostly to
 187      * applications).
 188      *
 189      * <p/>If this module is a {@link PeerGroup} service, it may be invoked
 190      * several times depending on its return value.
 191      *
 192      * @param args An array of Strings forming the parameters for this
 193      * Module.
 194      *
 195      * @return int A status indication which may be one of
 196      * {@link #START_OK}, {@link #START_AGAIN_PROGRESS},
 197      * {@link #START_AGAIN_STALLED}, which indicates partial or complete
 198      * success, or any other value (negative values are
 199      * recommended for future compatibility), which indicates failure.
 200      **/
 201     public int startApp(String[] args);
 202
 203     /**
 204      *  Stop a module. This may be called any time after <code>init()</code>
 205      *  completes and should not assume that <code>startApp()</code> has been
 206      *  called or completed.
 207      *
 208      *  <p/>The Module cannot be forced to comply, but in the future
 209      *  we might be able to deny it access to anything after some timeout.
 210      **/
 211     public void stopApp();
 212 }