javax.portlet.BaseURL 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.
*/
/*
* NOTE: this source code is based on an early draft version of JSR 286 and not intended for product
* implementations. This file may change or vanish in the final version of the JSR 286 specification.
*/
/*
* 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!
*/
/**
* Copyright 2006 IBM Corporation.
*/
package javax.portlet;
/**
* The BaseURL defines the basic capabilities
* of a portlet URL pointing back to the portlet.
*
* @since 2.0
*/
public interface BaseURL {
/**
* Sets the given String parameter to this URL.
*
* This method replaces all parameters with the given key.
*
* The PortletURL implementation 'x-www-form-urlencoded' encodes
* all parameter names and values. Developers should not encode them.
*
* A portlet container may prefix the attribute names internally
* in order to preserve a unique namespace for the portlet.
*
* A parameter value of null indicates that this
* parameter should be removed.
*
* @param name
* the parameter name
* @param value
* the parameter value
*
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public void setParameter (String name, String value);
/**
* Sets the given String array parameter to this URL.
*
* This method replaces all parameters with the given key.
*
* The PortletURL implementation 'x-www-form-urlencoded' encodes
* all parameter names and values. Developers should not encode them.
*
* A portlet container may prefix the attribute names internally
* in order to preserve a unique namespace for the portlet.
*
* @param name
* the parameter name
* @param values
* the parameter values
*
* @exception java.lang.IllegalArgumentException
* if name is null.
*/
public void setParameter (String name, String[] values);
/**
* Sets a parameter map for this URL.
*
* All previously set parameters are cleared.
*
* The PortletURL implementation 'x-www-form-urlencoded' encodes
* all parameter names and values. Developers should not encode them.
*
* A portlet container may prefix the attribute names internally,
* in order to preserve a unique namespace for the portlet.
*
* @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. The values
* in the parameter map must be of type
* String array (String[]).
*
* @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.
*/
public void setParameters(java.util.Map parameters);
/**
* Indicated the security setting for this URL.
*
* Secure set to true indicates that the portlet requests
* a secure connection between the client and the portlet window for
* this URL. Secure set to false indicates that the portlet
* does not need a secure connection for this URL. If the security is not
* set for a URL, it should stay the same as the current request.
*
* @param secure true, if portlet requests to have a secure connection
* between its portlet window and the client; false, if
* the portlet does not require a secure connection.
*
* @throws PortletSecurityException if the run-time environment does
* not support the indicated setting
*/
public void setSecure (boolean secure) throws PortletSecurityException;
/**
* Returns the portlet URL string representation to be embedded in the
* markup.
* Note that the returned String may not be a valid URL, as it may
* be rewritten by the portal/portlet-container before returning the
* markup to the client.
*
* The returned URL is not XML escaped.
*
* For writing URLs to an output stream the {@link #write(java.io.Writer)} or
* {@link #write(java.io.Writer, boolean)} method should be used as these are
* more efficient.
*
* @return the encoded URL as a string
*/
public String toString ();
/**
* Returns a Map of the parameters
* currently set on this portlet URL via the
* setParameter or setParameters
* methods.
*
* The values in the returned Map are from type
* String array (String[]).
*
* If no parameters exist this method returns an empty Map.
*
* @return Map containing 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[]).
*
* @since 2.0
*/
public java.util.Map getParameterMap();
/**
* Writes the portlet URL to the output stream using the provided writer.
*
* Note that the URL written to the output stream may not be a valid URL, as it may
* be rewritten by the portal/portlet-container before returning the
* markup to the client.
*
* The URL written to the output stream is always XML escaped. For writing
* non-escaped URLs use {@link #write(java.io.Writer, boolean)}.
*
* @param out the writer to write the portlet URL to
* @throws java.io.IOException if an I/O error occured while writing the URL
*
* @since 2.0
*/
public void write(java.io.Writer out) throws java.io.IOException;
/**
* Writes the portlet URL to the output stream using the provided writer.
* If the parameter escapeXML is set to true the URL will be escaped to be
* valid XML characters, i.e. <, >, &, ', " will get converted
* into their corresponding character entity codes (< to &<, > to &>,
* & to &&, ' to &', " to &").
* If escapeXML is set to false no escaping will be done.
*
* Note that the URL written to the output stream may not be a valid URL, as it may
* be rewritten by the portal/portlet-container before returning the
* markup to the client.
*
* @param out the writer to write the portlet URL to
* @param escapeXML denotes if the URL should be XML escaped before written to the output
* stream or not
* @throws java.io.IOException if an I/O error occurred while writing the URL
*
* @since 2.0
*/
public void write(java.io.Writer out, boolean escapeXML) throws java.io.IOException;
/**
* Adds a String property to an existing key on the URL.
*
* This method allows URL properties to have multiple values.
*
* Properties can be used by portlets to provide vendor specific information
* to the URL.
*
* @param key
* the key of the property
* @param value
* the value of the property
*
* @exception java.lang.IllegalArgumentException
* if key is null.
*
* @since 2.0
*/
public void addProperty(String key, String value);
/**
* Sets a String property on the URL.
*
* Properties can be used by portlets to provide vendor specific information
* to the URL.
*
* This method resets all properties previously added with the same key.
*
* @param key
* the key of the property
* @param value
* the value of the property
*
* @exception java.lang.IllegalArgumentException
* if key is null.
*
* @since 2.0
*/
public void setProperty(String key, String value);
}