Container.java 5.2 KB
Newer Older
Matt Tucker's avatar
Matt Tucker committed
1
/**
Matt Tucker's avatar
Matt Tucker committed
2 3 4 5
 * $RCSfile$
 * $Revision$
 * $Date$
 *
Matt Tucker's avatar
Matt Tucker committed
6
 * Copyright (C) 2004 Jive Software. All rights reserved.
Matt Tucker's avatar
Matt Tucker committed
7
 *
Matt Tucker's avatar
Matt Tucker committed
8 9
 * This software is published under the terms of the GNU Public License (GPL),
 * a copy of which is included in this distribution.
Matt Tucker's avatar
Matt Tucker committed
10
 */
Matt Tucker's avatar
Matt Tucker committed
11

Matt Tucker's avatar
Matt Tucker committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
package org.jivesoftware.messenger.container;

import org.jivesoftware.messenger.auth.UnauthorizedException;

/**
 * Acts as a centralized coordinator of JVM-wide resources in the container.
 * Components may directly access the container resources using the
 * methods and resulting resource controllers. The container is passed to
 * the module in it's initialize method.
 *
 * @author Iain Shigeoka
 */
public interface Container {

    /**
     * <p>Obtain the setup mode status of the container.</p>
     * <p>If the container is in setup mode, return true. This is set to
     * true if the jive property "setup" is not set to true. The property
     * indicates that setup has already occured, while this method reports
     * the setup status (true, you're in setup mode). Setup code should
     * set the jive property "setup" to "true" by using the container's
     * module context Container.getModuleContext().</p>
     *
     * @return True if the container is in setup mode
     */
    boolean isSetupMode();

    /**
     * <p>Flag indicating if the container was started in stand alone mode.
     * If the container is in stand alone mode, return true. Stand alone
     * containers may be stopped.</p>
     *
     * @return True if the container is in stand alone mode
     */
    boolean isStandAlone();

    /**
     * <p>Flag indicating if the container can be restarted.
     * The container is restartable only if it is stand alone and
     * a service wrapper deployment was used.</p>
     *
     * @return True if the container can be restarted
     */
    boolean isRestartable();

    /**
     * Obtain the service lookup for the server. The service lookup may
     * contain remote services. You should use the localServerAttribute to
     * locate services that are known to be local to the server.
     *
     * @return The service lookup for finding and posting service items
     * @throws UnauthorizedException If the caller does not have permission to
     *                               access this resource
     */
    ServiceLookup getServiceLookup() throws UnauthorizedException;

    /**
     * <p/>
     * The container will attempt to start the given service if support
     * classes can be found.
     * </p>
     * <p/>
     * A container may not know about the requested service so
     * callers should be prepared for a null return. The call blocks
     * during service initializiation and startup so there may
     * be some delays during the method call.
     * </p>
     *
     * @param service The service to be started
     * @return The service instance or null if one could not be started
     * @throws UnauthorizedException If the caller does not have permission to
     *                               access this resource
     */
    Object startService(Class service) throws UnauthorizedException;

    /**
     * <p/>
     * The container will attempt to stop the all matching services in
     * the container.
     * </p>
     * <p/>
     * A container may not know about the requested service or it may
     * refuse to stop the service even if an authorized exception
     * is not thrown. The call blocks during service shutdon so there may
     * be some delays during the method call. In many cases, stopping a service
     * will initiate the service stopping, but complete shutdown of the service
     * may occur later on a separate thread (for example while waiting for
     * transactions in progress to commit). It is not safe to assume that
     * a successful return from this method means the service has finished
     * shutting down.
     * </p>
     *
     * @param service The service to be stopped
     * @throws UnauthorizedException If the caller does not have permission
     *                               to access this resource
     */
    void stopService(Class service) throws UnauthorizedException;

    /**
     * Obtain a special entry that modules can use to locate or register local services in
     * the service registrar.
     * <p/>
     * To help modules locate other modules, a Jini service registrar is
     * provided. An entry is also given to narrow service
     * search for modules that are in the local JVM.
     * If your module needs to register itself with the registrar, it should
     * add the local attribute entry to it's entry sets.
     * </p>
     *
     * @return An Entry attribute used to mark local services/modules
     * @throws UnauthorizedException
     */
    Entry getLocalServerAttribute() throws UnauthorizedException;

    /**
     * <p>Stops the container and all hosted services.</p>
     * <p>In standalone mode, this also shuts down the server VM.
     * For app server deployments nothing happens.</p>
     *
     * @throws UnauthorizedException
     */
    void stop() throws UnauthorizedException;

    /**
     * <p>Restarts the container and all it's hosted services. If the
     * container is not restartable, this method does nothing.</p>
     *
     * @throws UnauthorizedException
     */
    void restart() throws UnauthorizedException;
}