org.apache.sling.api.scripting.SlingBindings 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 java.io.PrintWriter;
import java.io.Reader;
import java.util.HashMap;
import org.jetbrains.annotations.Nullable;
import org.apache.sling.api.SlingHttpServletRequest;
import org.apache.sling.api.SlingHttpServletResponse;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceResolver;
import org.slf4j.Logger;
/**
* The SlingBindings class is used to prepare global variables
* for script execution. The constants in this class define names of variables
* which MUST or MAY be provided for the script execution.
* Other variables may be define as callers see fit.
*/
public class SlingBindings extends HashMap {
private static final long serialVersionUID = 209505693646323450L;
/**
* The name of the global scripting variable providing the
* {@link org.apache.sling.api.SlingHttpServletRequest} object (value is
* "request"). The value of the scripting variable is the same as that
* returned by the
* {@link org.apache.sling.api.scripting.SlingScriptHelper#getRequest()}
* method.
*
* This bound variable is required in the bindings given the script.
*/
public static final String REQUEST = "request";
/**
* The name of the global scripting variable providing the
* {@link org.apache.sling.api.SlingHttpServletResponse} object (value is
* "response"). The value of the scripting variable is the same as that
* returned by the
* {@link org.apache.sling.api.scripting.SlingScriptHelper#getResponse()}
* method.
*
* This bound variable is required in the bindings given the script.
*/
public static final String RESPONSE = "response";
/**
* The name of the global scripting variable providing the
* {@link java.io.Reader} object (value is "reader").
*
* This bound variable is required in the bindings given the script.
*/
public static final String READER = "reader";
/**
* The name of the global scripting variable providing the
* {@link org.apache.sling.api.scripting.SlingScriptHelper} for the request
* (value is "sling").
*
* This bound variable is optional. If existing, the script helper instance
* must be bound to the same request and response objects as bound with the
* {@link #REQUEST} and {@link #RESPONSE} variables. If this variable is not
* bound, the script implementation will create it before actually
* evaluating the script.
*/
public static final String SLING = "sling";
/**
* The name of the global scripting variable providing the
* {@link org.apache.sling.api.resource.Resource} object (value is
* "resource"). The value of the scripting variable is the same as that
* returned by the SlingScriptHelper.getRequest().getResource()
* method.
*
* This bound variable is optional. If existing, the resource must be bound
* to the same resource as returned by the
* SlingHttpServletRequest.getResource() method. If this
* variable is not bound, the script implementation will bind it before
* actually evaluating the script.
*/
public static final String RESOURCE = "resource";
/**
*
* The name of the global scripting variable providing the
* {@link org.apache.sling.api.resource.ResourceResolver} object (value is
* "resolver"). The value of the scripting variable is the same as that
* returned by the {@code SlingScriptHelper.getRequest().getResourceResolver()}
* method.
*
*
* This bound variable is optional. If existing, the resource resolver must be
* bound to the same resolver as returned by the {@code
* SlingHttpServletRequest.getResource().getResourceResolver} method. If this
* variable is not bound, the script implementation will bind it before actually
* evaluating the script.
*
*/
public static final String RESOLVER = "resolver";
/**
* The name of the global scripting variable providing the
* java.io.PrintWriter object to return the response content
* (value is "out"). The value of the scripting variable is the same as that
* returned by the SlingScriptHelper.getResponse().getWriter()
* method.
*
* Note, that it may be advisable to implement a lazy acquiring writer for
* the out variable to enable the script to write binary data to
* the response output stream instead of the writer.
*
* This bound variable is optional. If existing, the resource must be bound
* to the same writer as returned by the
* SlingHttpServletResponse.getWriter() method of the
* response object bound to the {@link #RESPONSE} variable. If this variable
* is not bound, the script implementation will bind it before actually
* evaluating the script.
*/
public static final String OUT = "out";
/**
* The name of the global scripting variable indicating whether the output
* used by the script should be flushed after the script evaluation ended
* normally (value is "flush").
*
* The type of this variable is java.lang.Boolean indicating
* whether to flush the output (value is TRUE) or not (value
* is FALSE). If the variable has a non-null
* value of another type, the output is not flush as if the value would be
* FALSE.
*/
public static final String FLUSH = "flush";
/**
* The name of the global scripting variable providing a logger which may be
* used for logging purposes (value is "log"). The logger provides the API
* defined by the SLF4J org.slf4j.Logger interface.
*
* This bound variable is optional. If this variable is not bound, the
* script implementation will bind it before actually evaluating the script.
*/
public static final String LOG = "log";
/**
* Helper method to get an object with a given type from this map.
* @param key The key for the object
* @param The object type
* @param type The object type
* @return The searched object if it has the specified type, otherwise null is returned.
*/
@SuppressWarnings("unchecked")
protected ObjectType get(final String key, final Class type) {
final Object o = this.get(key);
if ( type.isInstance(o) ) {
return (ObjectType)o;
}
return null;
}
/**
* Helper method which invokes {@link #put(Object, Object)} only if the value is not null.
* @param key The key of the object
* @param value The value
*/
protected void safePut(final String key, final Object value) {
if ( value != null ) {
this.put(key, value);
}
}
/**
* Sets the {@link #FLUSH} property to flush.
* @param flush Whether to flush or not
*/
public void setFlush(boolean flush) {
put(FLUSH, flush);
}
/**
* Returns the {@link #FLUSH} property if not null and a
* boolean. Otherwise false is returned.
* @return {@code true} if flush
*/
public boolean getFlush() {
Boolean value = this.get(FLUSH, Boolean.class);
if (value != null ) {
return value;
}
return false;
}
/**
* Sets the {@link #LOG} property to log if not
* null.
* @param log The logger
*/
public void setLog(Logger log) {
this.safePut(LOG, log);
}
/**
* Returns the {@link #LOG} property if not null and a
* org.slf4j.Logger instance. Otherwise null
* is returned.
* @return The logger or {@code null}
*/
public @Nullable Logger getLog() {
return this.get(LOG, Logger.class);
}
/**
* Sets the {@link #OUT} property to out if not
* null.
* @param out The print writer
*/
public void setOut(PrintWriter out) {
this.safePut(OUT, out);
}
/**
* Returns the {@link #OUT} property if not null and a
* PrintWriter instance. Otherwise null is
* returned.
* @return The print writer or {@code null}
*/
public @Nullable PrintWriter getOut() {
return this.get(OUT, PrintWriter.class);
}
/**
* Sets the {@link #REQUEST} property to request if not
* null.
* @param request The request object.
*/
public void setRequest(SlingHttpServletRequest request) {
this.safePut(REQUEST, request);
}
/**
* Returns the {@link #REQUEST} property if not null and a
* SlingHttpServletRequest instance. Otherwise
* null is returned.
* @return The request object or {@code null}
*/
public @Nullable SlingHttpServletRequest getRequest() {
return this.get(REQUEST, SlingHttpServletRequest.class);
}
/**
* Sets the {@link #READER} property to reader if not
* null.
* @param reader The reader
*/
public void setReader(Reader reader) {
this.safePut(READER, reader);
}
/**
* Returns the {@link #READER} property if not null and a
* Reader instance. Otherwise null is
* returned.
* @return The reader or {@code null}.
*/
public @Nullable Reader getReader() {
return this.get(READER, Reader.class);
}
/**
* Sets the {@link #RESOURCE} property to resource if not
* null.
* @param resource The resource
*/
public void setResource(Resource resource) {
this.safePut(RESOURCE, resource);
}
/**
* Returns the {@link #RESOURCE} property if not null and a
* Resource instance. Otherwise null is
* returned.
* @return The resource or {@code null}.
*/
public @Nullable Resource getResource() {
return this.get(RESOURCE, Resource.class);
}
/**
* Sets the {@link #RESOLVER} property to the provided {@code resourceResolver} if not {@code null}.
* @param resourceResolver the Resource Resolver
*/
public void setResourceResolver(ResourceResolver resourceResolver) {
this.safePut(RESOLVER, resourceResolver);
}
/**
* Returns the {@link #RESOLVER} property if not null and a
* ResourceResolver instance. Otherwise null is
* returned.
* @return the bound {@link ResourceResolver} if one exists, null otherwise
*/
public @Nullable ResourceResolver getResourceResolver() {
return this.get(RESOLVER, ResourceResolver.class);
}
/**
* Sets the {@link #RESPONSE} property to response if not
* null.
* @param response The response
*/
public void setResponse(SlingHttpServletResponse response) {
this.safePut(RESPONSE, response);
}
/**
* Returns the {@link #RESPONSE} property if not null and a
* SlingHttpServletResponse instance. Otherwise
* null is returned.
* @return The response or {@code null}.
*/
public @Nullable SlingHttpServletResponse getResponse() {
return this.get(RESPONSE, SlingHttpServletResponse.class);
}
/**
* Sets the {@link #SLING} property to sling if not
* null.
* @param sling The script helper
*/
public void setSling(SlingScriptHelper sling) {
this.safePut(SLING, sling);
}
/**
* Returns the {@link #SLING} property if not null and a
* SlingScriptHelper instance. Otherwise null
* is returned.
* @return The script helper or {@code null}.
*/
public @Nullable SlingScriptHelper getSling() {
return this.get(SLING, SlingScriptHelper.class);
}
}