javax.portlet.StateAwareResponse 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
* StateAwareResponse represents a response that can modify
* render state information or send events.
*
* If the render state is modified through this interface, the changes take
* effect for subsequent portlet render phase processing.
*
*
* @since 2.0
* @see RenderState
* @see PortletResponse
*/
public interface StateAwareResponse extends PortletResponse, MutableRenderState {
/**
* Sets
* a parameter map for the render request.
*
*
* These parameters will be accessible in all sub-sequent render calls via
* the PortletRequest.getParameter call until a new request
* is targeted to the portlet.
*
* The given parameters do not need to be encoded prior to calling this
* method.
*
* The portlet should not modify the map any further after calling
* this method.
*
*
*
* This method can be used to set both public and private render parameters.
*
* These parameters will be accessible in all subsequent render calls via the
* PortletRequest.getParameter call until a new request is targeted to the portlet.
*
* Any previously set private render parameter that is not contained in the new map
* is removed. However, public render parameters cannot be removed by excluding
* them from the map. Public render parameters that are not included in the map
* remain unchanged.
*
* The given parameters do not need to be encoded prior to calling this method.
*
* The portlet should not modify the map any further after calling this method.
*
*
* @param parameters
*
* Map containing parameter names for the render phase as keys and
* parameter values as map values. The keys in the parameter map must be of type
* String and may not be null or the empty string (""). The values in the parameter
* map must be of type String array (String[]).
* The values array may not be null;
* however, the values array elements may be null.
*
*
* @exception java.lang.IllegalArgumentException
*
* if parameters is null, if any of the
* keys in the Map are null, if any of
* the keys is not a String, or if any of the values is not a
* String array.
*
* @exception java.lang.IllegalStateException
* if the method is invoked after sendRedirect
* has been called.
*
* @deprecated As of version 3.0. Use {@link #getRenderParameters()} instead.
*/
@Deprecated
public void setRenderParameters(java.util.Map parameters);
/**
* Sets
* a String parameter for the render request.
*
*
* These parameters will be accessible in all subsequent render calls
* until an action or render request is
* targeted to the portlet.
*
*
* This method replaces all parameters with the given key.
*
* The given parameter do not need to be encoded prior to calling this
* method.
*
*
* A parameter value of null indicates that this
* parameter should be removed.
* However, an empty string value ("") is allowed.
*
*
* @param key
* key of the render parameter
* @param value
* value of the render parameter
*
* @exception java.lang.IllegalArgumentException
* if key is null;
*
* if an attempt is made to set a public render parameter to null.
*
* @exception java.lang.IllegalStateException
* if the method is invoked after sendRedirect
* has been called.
*
* @deprecated As of version 3.0. Use {@link #getRenderParameters()} instead.
*/
@Deprecated
public void setRenderParameter(String key, String value);
/**
* Sets
* a multi-valued String parameter for the render request.
*
*
* These parameters will be accessible in all subsequent render calls
* until an action or render request is
* targeted to the portlet.
*
*
* This method replaces all parameter values with the given key.
*
* The given parameter do not need to be encoded prior to calling this
* method.
*
*
* A values parameter of null indicates that this
* parameter should be removed.
*
*
*
* If the values parameter is not null, elements of the array may be null.
*
*
* @param key
* key of the render parameter
* @param values
* values of the render parameter
*
* @exception java.lang.IllegalArgumentException
* if name is null;
*
* if an element of the values array is null;
* if an attempt is made to set a public render parameter to null.
*
* @exception java.lang.IllegalStateException
* if the method is invoked after sendRedirect
* has been called.
*
* @deprecated As of version 3.0. Use {@link #getRenderParameters()} instead.
*/
@Deprecated
public void setRenderParameter(String key, String... values);
/**
* Publishes an Event with the given payload.
*
* The object type of the value must be compliant with the specified event
* type in the portlet deployment descriptor.
*
* The value must have a valid JAXB binding and be serializable.
*
* @param name
* the event name to publish, must not be null
* @param value
* the value of this event, must have a valid JAXB binding and
* be serializable, or null.
*
* @exception java.lang.IllegalArgumentException
* if name is null, the value is not
* serializable, the value does not have a valid JAXB binding, the
* object type of the value is not the same as specified in
* the portlet deployment descriptor for this event name.
* @since 2.0
*/
public void setEvent(javax.xml.namespace.QName name, java.io.Serializable value);
/**
* Publishes an Event with the given payload in the default namespace.
*
* The name is treated as local part of the event QName and the namespace
* is either taken from the default-event-namespace element
* in the portlet deployment descriptor, or if this element is not provided
* the XML default namespace XMLConstants.NULL_NS_URI is used.
*
* The object type of the value must be compliant with the specified event
* type in the portlet deployment descriptor.
*
* The value must have a valid JAXB binding and be serializable.
*
* @param name
* the local part of the event name to publish, must not be null
* @param value
* the value of this event, must have a valid JAXB binding and
* be serializable, or null.
*
* @exception java.lang.IllegalArgumentException
* if name is null, the value is not
* serializable, the value does not have a valid JAXB binding, the
* object type of the value is not the same as specified in
* the portlet deployment descriptor for this event name.
* @since 2.0
*/
public void setEvent(String name, java.io.Serializable value);
/**
* Returns a Map of the render parameters currently set on
* this response.
*
* The values in the returned Map are of type String array (String[]).
*
* The contents of the returned map are immutable in the sense that modifying the map does not directly
* affect the render parameters. In order to set the parameters using the modified map,
* the {@link StateAwareResponse#setRenderParameters(Map)} method must be used.
*
*
* If no parameters exist this method returns an empty Map.
*
* @since 2.0
*
* @return Map containing render parameter names as keys and
* parameter values as map values, or an empty Map if
* no parameters exist. The keys in the parameter map are of type
* String. The values in the parameter map are of type String array (String[]).
*
* @deprecated As of version 3.0. Use {@link #getRenderParameters()} instead.
*/
@Deprecated
public java.util.Map getRenderParameterMap();
/**
* Removes the specified public render parameter.
* The name must reference a public render parameter defined
* in the portlet deployment descriptor under the
* public-render-parameter element with the
* identifier mapping to the parameter name.
*
* @param name a String specifying
* the name of the public render parameter to be removed
*
* @exception java.lang.IllegalArgumentException
* if name is null.
* @since 2.0
*
* @deprecated As of version 3.0. Use {@link #getRenderParameters()} instead.
*/
@Deprecated
public void removePublicRenderParameter(String name);
}