org.glassfish.embeddable.web.WebContainer Maven / Gradle / Ivy
/*
* 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 java.util.logging.Level;
import org.glassfish.embeddable.GlassFishException;
import org.glassfish.embeddable.web.config.WebContainerConfig;
/**
* Class representing an embedded web container, which supports the
* programmatic creation of different types of web protocol listeners
* and virtual servers, and the registration of static and dynamic
* web resources into the URI namespace.
*
* WebContainer service can be accessed using GlassFish instance.
*
* Usage example:
*
*
* // Create and start GlassFish
* GlassFish glassfish = GlassFishRuntime.bootstrap().newGlassFish();
* glassfish.start();
*
* // Access WebContainer
* WebContainer container = glassfish.getService(WebContainer.class);
*
* // Create and add {@link WebListener}
* // By default, when GlassFish Embedded Server starts, no web listener is enabled
* WebListener listener = container.createWebListener("listener-1", HttpListener.class);
* listener.setPort(8080);
* container.addWebListener(listener);
*
* // Create and register web resources {@link Context}.
* File docroot = new File(path_to_web_resources);
* Context context = container.createContext(docroot);
* container.addContext(context, "contextroot_to_register");
*
* // Create and add {@link VirtualServer}
* // By default, when GlassFish Embedded Server starts,
* // a virtual server named server starts automatically.
* VirtualServer virtualServer = (VirtualServer)
* container.createVirtualServer("embedded-server", new File(docroot_of_VirtualServer));
* VirtualServerConfig config = new VirtualServerConfig();
* config.setHostNames("localhost");
* virtualServer.setConfig(config);
* container.addVirtualServer(virtualServer);
*
*/
public interface WebContainer {
/**
* Sets the embedded configuration for this embedded instance.
* Such configuration will always override any xml based
* configuration.
*
* @param config the embedded instance configuration
*/
public void setConfiguration(WebContainerConfig config);
/**
* Creates a Context and configures it with the given
* docroot and classloader.
*
* The classloader of the class on which this method is called
* will be used.
*
*
In order to access the new Context or any of its
* resources, the Context must be registered with a
* VirtualServer that has been started using either
* WebContainer#addContext or VirtualServer#addContext method.
*
* @param docRoot the docroot of the Context
*
* @return the new Context
*
* @see VirtualServer#addContext
*/
public Context createContext(File docRoot);
/**
* Creates a Context and configures it with the given
* docroot and classloader.
*
*
The given classloader will be set as the thread's context
* classloader whenever the new Context or any of its
* resources are asked to process a request.
* If a null classloader is passed, the classloader of the
* class on which this method is called will be used.
*
*
In order to access the new Context or any of its
* resources, the Context must be registered with a
* VirtualServer that has been started using either
* WebContainer#addContext or VirtualServer#addContext method.
*
* @param docRoot the docroot of the Context
* @param classLoader the classloader of the Context
*
* @return the new Context
*
* @see VirtualServer#addContext
*/
public Context createContext(File docRoot, ClassLoader classLoader);
/**
* Creates a Context, configures it with the given
* docroot and classloader, and registers it with all
* VirtualServer.
*
*
The given classloader will be set as the thread's context
* classloader whenever the new Context or any of its
* resources are asked to process a request.
* If a null classloader is passed, the classloader of the
* class on which this method is called will be used.
*
* @param docRoot the docroot of the Context
* @param contextRoot the contextroot at which to register
* @param classLoader the classloader of the Context
*
* @return the new Context
*/
public Context createContext(File docRoot, String contextRoot,
ClassLoader classLoader);
/**
* Registers the given Context with all VirtualServer
* at the given context root.
*
*
If 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 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 all
* 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 ConfigException, GlassFishException;
/**
* Creates a WebListener from the given class type and
* assigns the given id to it.
*
* @param id the id of the new WebListener
* @param c the class from which to instantiate the
* WebListener
*
* @return the new WebListener instance
*
* @throws IllegalAccessException if the given Class or
* its nullary constructor is not accessible.
* @throws InstantiationException if the given Class
* represents an abstract class, an interface, an array class,
* a primitive type, or void; or if the class has no nullary
* constructor; or if the instantiation fails for some other reason.
* @throws ExceptionInInitializerError if the initialization
* fails
* @throws SecurityException if a security manager, s, is
* present and any of the following conditions is met:
*
*
* - invocation of {@link SecurityManager#checkMemberAccess
* s.checkMemberAccess(this, Member.PUBLIC)} denies
* creation of new instances of the given Class
*
- the caller's class loader is not the same as or an
* ancestor of the class loader for the current class and
* invocation of {@link SecurityManager#checkPackageAccess
* s.checkPackageAccess()} denies access to the package
* of this class
*
*/
public T createWebListener(String id, Class c)
throws InstantiationException, IllegalAccessException;
/**
* Adds the given WebListener to this
* WebContainer.
*
* If this WebContainer has already been started,
* the given webListener will be started as well.
*
* @param webListener the WebListener to add
*
* @throws ConfigException if a WebListener with the
* same id has already been registered with this
* WebContainer
* @throws GlassFishException if the given webListener fails
* to be started
*/
public void addWebListener(WebListener webListener)
throws ConfigException, GlassFishException;
/**
* Finds the WebListener with the given id.
*
* @param id the id of the WebListener to find
*
* @return the WebListener with the given id, or
* null if no WebListener with that id has been
* registered with this WebContainer
*/
public WebListener getWebListener(String id);
/**
* Gets the collection of WebListener instances registered
* with this WebContainer.
*
* @return the (possibly empty) collection of WebListener
* instances registered with this WebContainer
*/
public Collection getWebListeners();
/**
* Stops the given webListener and removes it from this
* WebContainer.
*
* @param webListener the WebListener to be stopped
* and removed
*
* @throws GlassFishException if an error occurs during the stopping
* or removal of the given webListener
*/
public void removeWebListener(WebListener webListener)
throws GlassFishException;
/**
* Creates a VirtualServer with the given id and docroot, and
* maps it to the given WebListener instances.
*
* @param id the id of the VirtualServer
* @param docRoot the docroot of the VirtualServer
* @param webListeners the list of WebListener instances from
* which the VirtualServer will receive requests
*
* @return the new VirtualServer instance
*/
public VirtualServer createVirtualServer(String id,
File docRoot, WebListener... webListeners);
/**
* Creates a VirtualServer with the given id and docroot, and
* maps it to all WebListener instances.
*
* @param id the id of the VirtualServer
* @param docRoot the docroot of the VirtualServer
*
* @return the new VirtualServer instance
*/
public VirtualServer createVirtualServer(String id, File docRoot);
/**
* Adds the given VirtualServer to this
* WebContainer.
*
* If this WebContainer has already been started,
* the given virtualServer will be started as well.
*
* @param virtualServer the VirtualServer to add
*
* @throws ConfigException if a VirtualServer with the
* same id has already been registered with this
* WebContainer
* @throws GlassFishException if the given virtualServer fails
* to be started
*/
public void addVirtualServer(VirtualServer virtualServer)
throws ConfigException, GlassFishException;
/**
* Finds the VirtualServer with the given id.
*
* @param id the id of the VirtualServer to find
*
* @return the VirtualServer with the given id, or
* null if no VirtualServer with that id has been
* registered with this WebContainer
*/
public VirtualServer getVirtualServer(String id);
/**
* Gets the collection of VirtualServer instances registered
* with this WebContainer.
*
* @return the (possibly empty) collection of VirtualServer
* instances registered with this WebContainer
*/
public Collection getVirtualServers();
/**
* Stops the given virtualServer and removes it from this
* WebContainer.
*
* @param virtualServer the VirtualServer to be stopped
* and removed
*
* @throws GlassFishException if an error occurs during the stopping
* or removal of the given virtualServer
*/
public void removeVirtualServer(VirtualServer virtualServer)
throws GlassFishException;
/**
* Sets log level
*
* @param level log level
*/
public void setLogLevel(Level level);
}