org.glassfish.embeddable.web.VirtualServer Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package org.glassfish.embeddable.web;

import java.io.File;
import java.util.Collection;
import org.glassfish.embeddable.web.config.VirtualServerConfig;
import org.glassfish.embeddable.GlassFishException;

/**
 * Representation of a virtual server.
 *
 * Instances of VirtualServer may be in one of two states:
 * stopped or started. Any requests mapped to a
 * VirtualServer that was stopped will result in a response with
 * a status code equal to
 * jakarta.servlet.http.HttpServletResponse#SC_NOT_FOUND.
 *
 * 
See {@link WebContainer} for usage example.
 *
 * @author Rajiv Mordani
 * @author Jan Luehe
 */
public interface VirtualServer {


    /**
     * Sets the id of this VirtualServer.
     *
     * @param ID id of this VirtualServer.
     */
    public void setID(String ID);

    /**
     * Gets the id of this VirtualServer.
     *
     * @return the id of this VirtualServer
     */
    public String getID();

    /**
     * Sets the docroot of this VirtualServer.
     *
     * @param docRoot the docroot of this VirtualServer.
     */
    public void setDocRoot(File docRoot);

    /**
     * Gets the docroot of this VirtualServer.
     *
     * @return the docroot of this VirtualServer
     */
    public File getDocRoot();

    /**
     * Gets the collection of WebListener instances from which
     * this VirtualServer receives requests.
     *
     * @return the collection of WebListener instances from which
     * this VirtualServer receives requests.
     */
    public Collection getWebListeners();

    /**
     * Adds the given Valve to this VirtualServer
     *
     * @param valve the Valve to be added
     */
    //public void addValve(Valve valve);

    /**
     * Registers the given Context with this VirtualServer
     * at the given context root.
     *
     * 
If this VirtualServer has already been started, the
     * given context will be started as well.
     *
     * @param context the Context to register
     * @param contextRoot the context root at which to register
     *
     * @throws ConfigException if a Context already exists
     * at the given context root on this VirtualServer
     * @throws GlassFishException if the given context fails
     * to be started
     */
    public void addContext(Context context, String contextRoot)
        throws ConfigException, GlassFishException;

    /**
     * Stops the given context and removes it from this
     * VirtualServer.
     *
     * @param context the Context to be stopped and removed
     *
     * @throws GlassFishException if an error occurs during the stopping
     * or removal of the given context
     */
    public void removeContext(Context context)
            throws GlassFishException;

    /**
     * Finds the Context registered at the given context root.
     *
     * @param contextRoot the context root whose Context to get
     *
     * @return the Context registered at the given context root,
     * or null if no Context exists at the given context
     * root
     */
    public Context getContext(String contextRoot);

    /**
     * Gets the collection of Context instances registered with
     * this VirtualServer.
     *
     * @return the (possibly empty) collection of Context
     * instances registered with this VirtualServer
     */
    public Collection getContexts();

    /**
     * Reconfigures this VirtualServer with the given
     * configuration.
     *
     * In order for the given configuration to take effect, this
     * VirtualServer may be stopped and restarted.
     *
     * @param config the configuration to be applied
     *
     * @throws ConfigException if the configuration requires a restart,
     * and this VirtualServer fails to be restarted
     */
    public void setConfig(VirtualServerConfig config)
        throws ConfigException;

    /**
     * Gets the current configuration of this VirtualServer.
     *
     * @return the current configuration of this VirtualServer,
     * or null if no special configuration was ever applied to this
     * VirtualServer
     */
    public VirtualServerConfig getConfig();
}