javax.portlet.MimeResponse Maven / Gradle / Ivy
Show all versions of portlet-api Show documentation
/* 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.
*/
/*
* This source code implements specifications defined by the Java
* Community Process. In order to remain compliant with the specification
* DO NOT add / change / or delete method signatures!
*/
package javax.portlet;
/**
* The
* MimeResponse defines the base interface to assist a
* portlet in returning MIME content.
*
* @since 2.0
*/
public interface MimeResponse extends PortletResponse {
/**
*
* Specifies processing when a URL is created.
*
*
* @see #createActionURL(Copy)
* @see #createRenderURL(Copy)
*
* @since 3.0
*/
public enum Copy {
/**
*
* Specifies that no parameters are to be copied when a URL is created.
*
*
* @since 3.0
*/
NONE,
/**
*
* Specifies that the public and private render parameters set for
* the current request are
* be copied to the URL when it is created.
*
*
* @since 3.0
*/
ALL,
/**
*
* Specifies that only the public render parameters set for the
* current request are be copied to the URL when it is created.
*
*
* @since 3.0
*/
PUBLIC;
}
/**
* Property to set the expiration time in seconds for this response using
* the setProperty method intended to be used in
* forwarded or included servlets/JSPs.
*
* If the expiration value is set to 0, caching is disabled for this
* portlet; if the value is set to -1, the cache does not expire.
*
* A default can be defined in the portlet deployment descriptor
* with the expiration-cache tag, otherwise it is 0.
*
* Non-integer values are treated as 0.
*
* The value is "portlet.expiration-cache".
*
* @see CacheControl
*/
public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
/**
* Property to set the cache scope for this response using the
* setProperty method intended to be used in
* forwarded or included servlets/JSPs.
*
* Predefined cache scopes are: PUBLIC_SCOPE and PRIVATE_SCOPE.
*
* A default can be defined in the portlet deployment descriptor
* with the cache-scope tag, otherwise it is PRIVATE_SCOPE.
*
* Values that are not either PUBLIC_SCOPE or PRIVATE_SCOPE
* are treated as PRIVATE_SCOPE.
*
* The value is "portlet.cache-scope".
*
* @see CacheControl
* @since 2.0
*/
public static final String CACHE_SCOPE = "portlet.cache-scope";
/**
* Public cache scope, indicating that the cache entry can be shared across
* users. The value is "portlet.public-scope".
*
* @since 2.0
*/
public static final String PUBLIC_SCOPE = "portlet.public-scope";
/**
* Private cache scope, indicating that the cache entry must not be shared
* across users. The value is "portlet.private-scope".
*
* @since 2.0
*/
public static final String PRIVATE_SCOPE = "portlet.private-scope";
/**
* Property to tell the portlet container the new ETag for this response
* intended to be used in forwarded or included servlets/JSPs.
*
* This property needs to be set using the setProperty method.
*
* The value is "portlet.ETag ".
*
* @see CacheControl
* @since 2.0
*/
public static final String ETAG = "portlet.ETag";
/**
* Property to tell the portlet container to use the cached markup
* for the validation token provided in the request. This property
* needs to be set using the setProperty method with a non-null
* value and is intended to be used in forwarded or included servlets/JSPs.
* The value itself is not evaluated.
*
* The value is "portlet.use-cached-content ".
*
* @see CacheControl
* @since 2.0
*/
public static final String USE_CACHED_CONTENT = "portlet.use-cached-content";
/**
* Property intended to be a hint to the portal application that the returned
* content is completely namespaced.
* This includes all markup id elements, form fields, etc.
* One example where this is might be used is for portal applications that
* are form-based and thus need to re-write any forms included in the portlet
* markup.
*
* This property needs to be set using the setProperty method with a non-null
* value. The value itself is not evaluated.
*
* The value is "X-JAVAX-PORTLET-NAMESPACED-RESPONSE".
*
* @since 2.0
*/
public static final String NAMESPACED_RESPONSE = "X-JAVAX-PORTLET-NAMESPACED-RESPONSE";
/**
* Property intended to be a hint to the portal application that the provided
* DOM element should be added to the markup head section of the response to the
* client.
*
* Support for this property is optional and the portlet can verify if the
* calling portal supports this property via the MARKUP_HEAD_ELEMENT_SUPPORT
* property on the PortalContext.
*
* Even if the calling portal support this property delivery of the DOM
* element to the client cannot be guaranteed, e.g. due to possible security
* rules of the portal application or elements that conflict with the
* response of other portlets.
*
* This property needs to be set using the
* setProperty(String key,org.w3c.dom.Element element)
* method.
*
* The value is "javax.portlet.markup.head.element".
*
* @since 2.0
*/
public static final String MARKUP_HEAD_ELEMENT = "javax.portlet.markup.head.element";
/**
* Returns the MIME type that can be used to contribute markup to the render
* response.
*
* If no content type was set previously using the {@link #setContentType}
* method this method returns null.
*
* @see #setContentType
*
* @return the MIME type of the response, or null if no
* content type is set
*/
public String getContentType();
/**
* Sets
* the MIME type for the response. The portlet should set the
* content type before calling {@link #getWriter} or
* {@link #getPortletOutputStream}.
*
* If the content type is not set using this method, the preferred
* content type as returned by {@link PortletRequest#getResponseContentType} is used.
*
*
* Calling setContentType after getWriter or
* getOutputStream does not change the content type.
*
*
* @param type
* the content MIME type
*
* @exception java.lang.IllegalArgumentException
*
* if the content type is invalid.
*
*
* @see PortletRequest#getResponseContentTypes
* @see #getContentType
*/
public void setContentType(String type);
/**
* Returns the name of the charset used for the MIME body sent in this
* response.
*
*
* See RFC 2047 for
* more information about character encoding and MIME.
*
* @return a String specifying the name of the charset, for
* example, ISO-8859-1
*
*/
public String getCharacterEncoding();
/**
* Returns a PrintWriter object that can send character text to the portal.
*
* Before calling this method the content type of the render response should
* be set using the {@link #setContentType} method.
*
* Either this method or {@link #getPortletOutputStream} may be called to
* write the body, not both.
*
* @return a PrintWriter object that can return character
* data to the portal
*
* @exception java.io.IOException
* if an input or output exception occurred
* @exception java.lang.IllegalStateException
* if the getPortletOutputStream method has
* been called on this response.
*
* @see #setContentType
* @see #getPortletOutputStream
*/
public java.io.PrintWriter getWriter() throws java.io.IOException;
/**
* Returns the locale assigned to the response.
*
* @return Locale of this response
*/
public java.util.Locale getLocale();
/**
* Sets the preferred buffer size for the body of the response. The portlet
* container will use a buffer at least as large as the size requested.
*
* This method must be called before any response body content is written;
* if content has been written, or the portlet container does not support
* buffering, this method may throw an IllegalStateException.
*
* @param size
* the preferred buffer size
*
* @exception java.lang.IllegalStateException
* if this method is called after content has been written,
* or the portlet container does not support buffering
*
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*/
public void setBufferSize(int size);
/**
* Returns the actual buffer size used for the response. If no buffering is
* used, this method returns 0.
*
* @return the actual buffer size used
*
* @see #setBufferSize
* @see #flushBuffer
* @see #isCommitted
* @see #reset
*/
public int getBufferSize();
/**
* Forces any content in the buffer to be written to the underlying output stream. A call to
* this method automatically commits the response.
*
* @exception java.io.IOException
* if an error occurred when writing the output
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
*/
public void flushBuffer() throws java.io.IOException;
/**
* Clears the content of the underlying buffer in the response without
* clearing properties set. If the response has been committed, this method
* throws an IllegalStateException.
*
* @exception IllegalStateException
* if this method is called after response is committed
*
* @see #setBufferSize
* @see #getBufferSize
* @see #isCommitted
* @see #reset
*/
public void resetBuffer();
/**
* Returns a boolean indicating if the response has been committed.
*
* @return a boolean indicating if the response has been committed
*
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #reset
*/
public boolean isCommitted();
/**
* Clears any data that exists in the buffer as well as the properties set.
* If the response has been committed, this method throws an
* IllegalStateException.
*
* @exception java.lang.IllegalStateException
* if the response has already been committed
*
* @see #setBufferSize
* @see #getBufferSize
* @see #flushBuffer
* @see #isCommitted
*/
public void reset();
/**
* Returns a OutputStream suitable for writing binary data in
* the response. The portlet container does not encode the binary data.
*
* Before calling this method the content type of the render response must
* be set using the {@link #setContentType} method.
*
* Calling flush() on the OutputStream commits the response.
*
* Either this method or {@link #getWriter} may be called to write the body,
* not both.
*
* @return a OutputStream for writing binary data
*
* @exception java.lang.IllegalStateException
* if the getWriter method has been called on
* this response.
*
* @exception java.io.IOException
* if an input or output exception occurred
*
* @see #setContentType
* @see #getWriter
*/
public java.io.OutputStream getPortletOutputStream()
throws java.io.IOException;
/**
*
* Creates a render URL targeting the portlet.
* Render URLs cause idempotent requests that move the portlet to a
* new view state, for example, to view a different page of data.
*
* If a request is triggered by the URL, it results in
* a render request.
*
*
*
* The returned render URL will not contain any private render parameters from the
* current request.
*
*
*
* The created URL will per default not contain any parameters of the
* current render request.
*
*
* The returned URL can be further extended by adding portlet-specific render
* parameters, portlet mode, and window state.
* If no portlet mode, window
* state or security modifier is set on the URL, the values from the
* current render or resource request are preserved.
*
*
* Public render parameters do not need to be explicitly added to the returned
* render URL, unless the public render parameter value is to be changed.
* Any public render parameters associated with
* the portlet will automatically be available during render request processing resulting
* from activation of the URL.
*
* If a public render parameter value is set or removed on a render URL, then the public
* render parameter will be set to the new value or removed when the URL is activated.
*
* The effect of this method is the same as calling {@link #createRenderURL(Copy)}
* with the parameter set to PUBLIC.
*
*
* @return a portlet render URL
*/
public T createRenderURL();
/**
*
* Creates a render URL targeting the portlet.
* Render URLs cause idempotent requests that move the portlet to a
* new view state, for example, to view a different page of data.
*
* If a request is triggered by the URL, it results in
* a render request.
*
* The new render URL will contain render parameters from the
* current request as specified by the option parameter.
*
* - NONE
* - All public and private parameters are removed from the URL.
* - ALL
* - The public and private parameters governing the current
* request are added to the URL.
* - PUBLIC
* - Only public parameters governing the current
* request are added to the URL.
*
* The URL can be further extended by adding render
* parameters, portlet mode, and window state.
* If no additional portlet mode, window
* state or security modifier is set on the URL, the values from the
* current render or resource request are preserved.
*
* If a public render parameter value is set or removed on a render URL, then the public
* render parameter will be set to the new value or removed when the URL is activated.
*
*
* @param option
* Specifies how current parameters are to be copied to the URL
*
* @see Copy
*
* @return a portlet render URL
*
* @since 3.0
*/
public RenderURL createRenderURL(Copy option);
/**
*
* Creates an action URL targeting the portlet.
* Action URLs are used to create forms or links that, when triggered,
* update the render state in a non-idempotent manner.
*
* If a request is triggered by the URL, it results in
* an action request.
*
*
* The returned action URL will
* not contain any private render parameters
* per default not contain any parameters
* from the current request.
*
* The returned URL can be further extended by adding portlet-specific action
* parameters, portlet mode, and window state.
* If no additional portlet mode, window
* state or security modifier is set on the URL, the values from the
* current render or resource request are preserved.
*
*
* Public render parameters do not need to be explicitly added to the returned
* action URL, unless the public render parameter value is to be changed.
* Any public render parameters associated with
* the portlet will automatically be available during action request
* processing resulting from activation of the URL.
*
* If a public render parameter value is set or removed on an action URL,
* then the public render parameter will be set to the new value or
* removed when the URL is activated.
*
* The effect of this method is the same as calling {@link #createRenderURL(Copy)}
* with the parameter set to PUBLIC.
*
*
* @return a portlet action URL
*/
public T createActionURL();
/**
*
* Creates an action URL targeting the portlet.
* Action URLs are used to create forms or links that, when triggered,
* update the render state in a non-idempotent manner.
*
* If a request is triggered by the URL, it results in
* an action request.
*
* The new action URL will contain render parameters from the
* current request as specified by the option parameter.
*
* - NONE
* - All public and private parameters are removed from the URL.
* - ALL
* - The public and private parameters governing the current
* request are added to the URL.
* - PUBLIC
* - Only public parameters governing the current
* request are added to the URL.
*
*
* The returned URL can be further extended by adding action
* parameters, portlet mode, and window state.
* If no additional portlet mode, window
* state or security modifier is set on the URL, the values from the
* current render or resource request are preserved.
*
* If a public render parameter value is set or removed on an action URL,
* then the public render parameter will be set to the new value or
* removed when the URL is activated.
*
*
* @param option
* Specifies how current parameters are to be copied to the URL
*
* @see Copy
*
* @return a portlet action URL
*
* @since 3.0
*/
public ActionURL createActionURL(Copy option);
/**
*
* Creates a resource URL targeting the portlet.
* Resource URLs are used to trigger requests for content that applies
* to the current portlet view state.
*
* If a request is triggered by the ResourceURL, it results in a serve
* resource request of the ResourceServingPortlet interface.
*
* The security settings can be changed for the URL. If the security settings are
* not explicitly set, the values governing the current request
* are preserved.
* The current
* render parameters, portlet mode, and window state are preserved
* depending on the cacheability setting for the returned resource URL.
*
*
*
* If cacheability is set to PORTLET or PAGE, the values of the render
* parameters, portlet mode, and window state are preserved.
* Otherwise, they will not be preserved.
*
* If allowed by the cacheability setting, public and private render
* parameters are added to the URL with their current values.
* The render parameter values cannot be changed on the URL.
*
* The URL can be further extended by adding portlet-specific resource
* parameters.
*
* The URL will contain the current
* cacheability setting of the parent resource by default.
* If no parent resource is available, PAGE is the default.
*
*
* If a request is triggered by the PortletURL, it results in a serve
* resource request of the ResourceServingPortlet interface.
*
* The returned URL can be further extended by adding portlet-specific
* parameters .
*
* The created URL will by default contain the current
* cacheability setting of the parent resource.
* If no parent resource is available, PAGE is the default.
*
*
* @since 2.0
* @return a portlet resource URL
*/
public ResourceURL createResourceURL();
/**
* Returns the cache control object allowing to set
* specific cache settings valid for the markup
* returned in this response.
*
* @return Cache control for the current response.
*
* @since 2.0
*/
public CacheControl getCacheControl();
}