org.apache.sling.api.scripting.SlingScriptHelper Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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.apache.sling.api.scripting;
import org.jetbrains.annotations.Nullable;
import org.jetbrains.annotations.NotNull;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.request.RequestDispatcherOptions;
import org.apache.sling.api.resource.Resource;
import org.osgi.annotation.versioning.ProviderType;
/**
* The SlingScriptHelper interface defines the API of a helper
* class which is provided to the scripts called from sling through the global
* {@link SlingBindings#SLING sling} variable.
*/
@ProviderType
public interface SlingScriptHelper {
/**
* Returns the {@link SlingHttpServletRequest} representing the input of the
* request.
* @return The request
*/
@NotNull SlingHttpServletRequest getRequest();
/**
* Returns the {@link SlingHttpServletResponse} representing the output of
* the request.
* @return The response
*/
@NotNull SlingHttpServletResponse getResponse();
/**
* Returns the {@link SlingScript} being called to handle the request.
* @return The script
*/
@NotNull SlingScript getScript();
/**
* Same as {@link #include(String,RequestDispatcherOptions)}, but using
* empty options.
*
* @param path The path to include
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
*/
void include(@NotNull String path);
/**
* Helper method to include the result of processing the request for the
* given path and requestDispatcherOptions.
* This method is intended to be implemented as follows:
*
*
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path,
* "option:xyz");
* if (dispatcher != null) {
* dispatcher.include(getRequest(), getResponse());
* }
*
*
*
* This method creates a RequestDispatcherOptions object by
* calling the
* {@link RequestDispatcherOptions#RequestDispatcherOptions(String)}
* constructor.
*
* @param path The path to the resource to include.
* @param requestDispatcherOptions influence the rendering of the included
* Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
* @see RequestDispatcherOptions#RequestDispatcherOptions(String)
* @see #include(String, RequestDispatcherOptions)
*/
void include(@NotNull String path, String requestDispatcherOptions);
/**
* Helper method to include the result of processing the request for the
* given path and options. This method is
* intended to be implemented as follows:
*
*
* RequestDispatcherOptions opts = new RequestDispatcherOptions();
* opts.put("option", "xyz");
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path, opts);
* if (dispatcher != null) {
* dispatcher.include(getRequest(), getResponse());
* }
*
*
* @param path The path to the resource to include.
* @param options influence the rendering of the included Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
* @see RequestDispatcherOptions
* @see #include(String, String)
*/
void include(@NotNull String path, RequestDispatcherOptions options);
/**
* Same as {@link #include(Resource,RequestDispatcherOptions)}, but using
* empty options.
*
* @param resource The resource to include
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
*/
void include(@NotNull Resource resource);
/**
* Helper method to include the result of processing the request for the
* given resource and requestDispatcherOptions.
* This method is intended to be implemented as follows:
*
*
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(resource,
* "option:xyz");
* if (dispatcher != null) {
* dispatcher.include(getRequest(), getResponse());
* }
*
*
*
* This method creates a RequestDispatcherOptions object by
* calling the
* {@link RequestDispatcherOptions#RequestDispatcherOptions(String)}
* constructor.
*
* @param resource The resource to include.
* @param requestDispatcherOptions influence the rendering of the included
* Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
* @see RequestDispatcherOptions#RequestDispatcherOptions(String)
* @see #include(String, RequestDispatcherOptions)
*/
void include(@NotNull Resource resource, String requestDispatcherOptions);
/**
* Helper method to include the result of processing the request for the
* given resource and options. This method is
* intended to be implemented as follows:
*
*
* RequestDispatcherOptions opts = new RequestDispatcherOptions();
* opts.put("option", "xyz");
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(resource, opts);
* if (dispatcher != null) {
* dispatcher.include(getRequest(), getResponse());
* }
*
*
* @param resource The resource to include.
* @param options influence the rendering of the included Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the include.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the include.
* @see RequestDispatcherOptions
* @see #include(String, String)
*/
void include(@NotNull Resource resource, RequestDispatcherOptions options);
/**
* Same as {@link #forward(String,RequestDispatcherOptions)}, but using
* empty options.
*
* @param path The path to forward to
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
*/
void forward(@NotNull String path);
/**
* Helper method to forward the request to a Servlet or script for the given
* path and requestDispatcherOptions. This method
* is intended to be implemented as follows:
*
*
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path,
* "option:xyz");
* if (dispatcher != null) {
* dispatcher.forward(getRequest(), getResponse());
* }
*
*
*
* This method creates a RequestDispatcherOptions object by
* calling the
* {@link RequestDispatcherOptions#RequestDispatcherOptions(String)}
* constructor.
*
* @param path The path to the resource to forward to.
* @param requestDispatcherOptions influence the rendering of the forwarded
* Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
* @see RequestDispatcherOptions#RequestDispatcherOptions(String)
* @see #forward(String, RequestDispatcherOptions)
*/
void forward(@NotNull String path, String requestDispatcherOptions);
/**
* Helper method to forward the request to a Servlet or script for the given
* path and options. This method is intended
* to be implemented as follows:
*
*
* RequestDispatcherOptions opts = new RequestDispatcherOptions();
* opts.put("option", "xyz");
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(path, opts);
* if (dispatcher != null) {
* dispatcher.forward(getRequest(), getResponse());
* }
*
*
* @param path The path to the resource to forward the request to.
* @param options influence the rendering of the forwarded Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
* @throws IllegalStateException If the respoonse has already been committed
* @see RequestDispatcherOptions
*/
void forward(@NotNull String path, RequestDispatcherOptions options);
/**
* Same as {@link #forward(Resource,RequestDispatcherOptions)}, but using
* empty options.
*
* @param resource The resource to forward to.
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
*/
void forward(@NotNull Resource resource);
/**
* Helper method to forward the request to a Servlet or script for the given
* resource and requestDispatcherOptions. This method
* is intended to be implemented as follows:
*
*
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(resource,
* "option:xyz");
* if (dispatcher != null) {
* dispatcher.forward(getRequest(), getResponse());
* }
*
*
*
* This method creates a RequestDispatcherOptions object by
* calling the
* {@link RequestDispatcherOptions#RequestDispatcherOptions(String)}
* constructor.
*
* @param resource The resource to forward to.
* @param requestDispatcherOptions influence the rendering of the forwarded
* Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
* @see RequestDispatcherOptions#RequestDispatcherOptions(String)
* @see #forward(String, RequestDispatcherOptions)
*/
void forward(@NotNull Resource resource, String requestDispatcherOptions);
/**
* Helper method to forward the request to a Servlet or script for the given
* resource and options. This method is intended
* to be implemented as follows:
*
*
* RequestDispatcherOptions opts = new RequestDispatcherOptions();
* opts.put("option", "xyz");
* RequestDispatcher dispatcher = getRequest().getRequestDispatcher(resource, opts);
* if (dispatcher != null) {
* dispatcher.forward(getRequest(), getResponse());
* }
*
*
* @param resource The resource to forward the request to.
* @param options influence the rendering of the forwarded Resource
* @throws org.apache.sling.api.SlingIOException Wrapping a IOException thrown
* while handling the forward.
* @throws org.apache.sling.api.SlingServletException Wrapping a ServletException
* thrown while handling the forward.
* @throws IllegalStateException If the respoonse has already been committed
* @see RequestDispatcherOptions
*/
void forward(@NotNull Resource resource, RequestDispatcherOptions options);
/**
* Lookup a single service.
*
* If multiple such services exist, the service with the highest ranking (as specified in its Constants.SERVICE_RANKING property) is returned.
* If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants.SERVICE_ID property); that is, the service that was registered first is returned.
*
* This is equal to the semantics from
*
* BundleContext.getServiceReference(Class).
* @param serviceType The type (interface) of the service.
* @param The type (interface) of the service.
* @return The service instance, or {@code null} if no services are registered which implement the specified class.
*/
@Nullable ServiceType getService(@NotNull Class serviceType);
/**
* Lookup one or several services.
*
* The returned array is sorted descending by service ranking (i.e. the service with the highest ranking is returned first).
* If there is a tie in ranking, the service with the lowest service ID
* (as specified in its Constants.SERVICE_ID property);
* that is, the service that was registered first is returned first.
*
*
* @param serviceType The type (interface) of the service.
* @param The type (interface) of the service.
* @param filter An optional filter (LDAP-like, see OSGi spec)
* @return An array of services objects or {@code null}.
* @throws InvalidServiceFilterSyntaxException If the filter
* string is not a valid OSGi service filter string.
*
* @see Filter class in OSGi
*/
@Nullable ServiceType[] getServices(@NotNull Class serviceType,
String filter);
/**
* Dispose the helper. This method can be used to clean up the script helper
* after the script is run.
* @deprecated This method is deprecated since version 2.1 and will be removed.
* It should never be called by clients.
*/
@Deprecated
void dispose();
}