javax.portlet.PortletParameters 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;
import java.util.Set;
/**
*
* The PortletParameters interface defines the API
* for accessing the parameters that are set for the portlet or on a portlet URL.
*
* Portlet parameters store state information that the portlet needs to render itself,
* generate content by serving resources, or make decisions when executing portlet
* actions. Conceptually the portlet parameters correspond to query string parameters
* that are stored in the URL used to access the portlet, although they are not
* required to actually be present on the URL as visible parameters.
*
* Private parameters parameters are available exclusively to a single portlet.
* Public parameters can be shared between portlets.
*
* The portlet parameters governing the request can be read during all portlet
* execution phases through the {@link PortletParameters} object available
* from the portlet request. Portlet parameters
* can be set for subsequent or future portlet execution phases through
* the {@link MutablePortletParameters} object available from the
* portlet response object or from the portlet URL.
*
* Different types of portlet parameters are distinguished
* according to their use.
*
* - Render Parameters
* -
* Set on the response during the Action and Event phases to govern content
* generation during the Render and Resource phases. Also set on render URLs
* to move the portlet to a new render state when the URL is triggered.
*
* Refer to {@link PortletRequest#getRenderParameters()},
* {@link StateAwareResponse#getRenderParameters()}, and
* {@link PortletURL#getRenderParameters()}.
*
* Example: Render URLs with differing render parameters can be used to
* implement tabbed navigation within a portlet.
*
* - Resource Parameters
* -
* Provide additional information about the content to be generated when
* serving a resource for the governing render state.
* Set on resource URLs and made available to the portlet through the
* resource request when the URL is triggered.
*
* Refer to {@link ResourceRequest#getResourceParameters()} and
* {@link ResourceURL#getResourceParameters()}.
*
* Example: Portlets may require several different pieces of content
* to be served for the governing render state.
* Resource URLs with differing resource parameters can be used to
* determine which content is to be served for a specific request.
*
* - Action Parameters
* -
* Provide additional information about the action to be executed
* for the governing render state.
* Set on action URLs and made available to the portlet through the
* action request when the URL is triggered, or provided to the
* portlet by the client (form parameters).
*
* Refer to {@link ActionRequest#getActionParameters()} and
* {@link ActionURL#getActionParameters()}.
*
* Example: Portlets may render a number of buttons or links
* for the governing render state.
* Action URLs with differing action parameters can be used to
* determine which action is to be executed for a specific request.
*
* Example: Portlets may render forms that, when submitted, may cause
* parameters to be added to the portlet action request.
* During action request processing, these form parameters will be available as
* action parameters.
*
*
*
* @see MutablePortletParameters
* @since 3.0
*/
public interface PortletParameters
{
/**
*
* Returns the value of a parameter as a String.
*
* Note that null is a valid parameter value.
* To determine whether a
* parameter is present, use the {@link java.util.Set#contains(Object)}
* method on the set returned by {@link #getNames()}.
*
* Only parameters targeted to the current portlet are accessible.
*
* This method should only be used if the
* parameter has only one value. If the parameter might have
* more than one value, use {@link #getValues}.
*
* If this method is used with a multivalued
* parameter, the value returned is equal to the first value
* in the array returned by getValues.
*
*
* @param name a String specifying the
* name of the parameter
*
* @return a String representing the
* single value of the parameter, or null.
*
* @see #getValues
* @see #getNames
* @since 3.0
*
* @exception java.lang.IllegalArgumentException
* if name is null.
*
*/
public String getValue(String name);
/**
*
* Returns a Set of String
* objects containing the names of the parameters contained
* in this object.
* Changing the Set has no effect on the originating
* PortletParameters object.
*
* Only parameter names targeted to the current portlet are returned.
*
*
*
* @return a Set of String
* objects, each String containing
* the name of a parameter; or an
* empty Set if the
* PortletParameters object has no parameters.
*
* @since 3.0
*/
public Set getNames();
/**
*
* Returns an array of String objects containing
* all of the values the given parameter, or
* null if the parameter does not exist.
*
* If the parameter has a single value, the array has a length
* of 1.
*
* Note that individual parameter values in the returned array
* may be null.
*
*
* @param name a String containing the name of
* the parameter the value of which is requested
*
* @return an array of String objects
* containing the parameter values, or null
* if the parameter does not exist.
*
* @see #getValue
* @since 3.0
*
* @exception java.lang.IllegalArgumentException
* if name is null.
*
*/
public String[] getValues(String name);
/**
*
* Returns a true if no parameters have been set.
*
*
* @return true if the object contains no parameters.
* false otherwise
*
* @since 3.0
*/
public boolean isEmpty ();
/**
*
* Returns the number of parameters in this object.
*
*
* @return the number of parameters in this object
*
* @since 3.0
*/
public int size();
/**
*
* Returns a MutablePortletParameters object encapsulating a copy of the same
* parameters as the original object.
* Changing a mutable copy will not influence the source object.
*
*
* @return Mutable clone of PortletParameters object
*
* @since 3.0
*/
public MutablePortletParameters clone();
}