org.ops4j.pax.web.service.whiteboard.ServletContextHelperMapping Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of pax-web-api Show documentation

Pax Web is a OSGi Http Service based on Jetty 6. Detailed information to be found at http://wiki.ops4j.org/confluence/x/AYAz.

The newest version!

/*
 * Copyright 2020 OPS4J.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.ops4j.pax.web.service.whiteboard;

import org.osgi.framework.Bundle;
import org.osgi.service.http.context.ServletContextHelper;

/**
 * ServletContextHelper mapping collects all the information required to register a
 * {@link ServletContextHelper} to allow referencing it later. This is actually not recommended Whiteboard service,
 * because OSGi CMPN Whiteboard specification mentions registrations of {@link ServletContextHelper} services
 * directly, with supporting service registration parameters, which is the OSGi way.
 *
 * Registering a {@link ServletContextHelper} can be done in two ways:

 *     registering a service with this interface - all the information is included in service itself
 *     (explicit whiteboard approach)
 *     registering a {@link ServletContextHelper} service, while required properties (mapping,
 *     name, parameters) are specified using service registration properties/annotations
 *     (OSGi CMPN Whiteboard approach)
 * 

 *
 * This interface doesn't extend {@link ContextRelated}, because it represents the context itself.
 *
 * Even if {@link #getServletContextHelper()} may return a singleton or a new instance on each call, this method
 * will be called once and the result will be treated as singleton.
 */
public interface ServletContextHelperMapping extends ContextMapping {

	/**
	 * Get actual context help being registered. If specified, this is the way to provide the behavioral
	 * aspects of the context (e.g., {@link ServletContextHelper#handleSecurity}). If not specified, default
	 * {@link ServletContextHelper} will be created according to {@link ContextMapping#getContextId()}.
	 *
	 * @return
	 */
	ServletContextHelper getServletContextHelper();

	/**
	 * Get actual context help being registered. This version accepts {@link Bundle}, so it's possible to
	 * return {@link ServletContextHelper} tied to given bundle. By default, {@link Bundle} argument is ignored and
	 * {@link #getServletContextHelper()} is called.
	 *
	 * This method reflects Whiteboard Service specification, where {@link ServletContextHelper} is recommended
	 * to be registered as {@link org.osgi.framework.ServiceFactory}.
	 *
	 * @return
	 */
	default ServletContextHelper getServletContextHelper(Bundle bundle) {
		return getServletContextHelper();
	}

}