You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pluto-scm@portals.apache.org by ms...@apache.org on 2014/11/25 13:50:21 UTC
[16/19] portals-pluto git commit: Moved the portlet spec 2 API
classes into the Pluto project in preparation for prototyping the Partial
Action sequence. The Partial Action implementation will require an update to
the ResourceRequest class in order to ma
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/MimeResponse.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/MimeResponse.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/MimeResponse.java
new file mode 100644
index 0000000..ee16254
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/MimeResponse.java
@@ -0,0 +1,423 @@
+/* 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 <CODE>MimeResponse</CODE> defines the base interface to assist a
+ * portlet in returning MIME content.
+ *
+ * @since 2.0
+ */
+public interface MimeResponse extends PortletResponse {
+
+ /**
+ * Property to set the expiration time in seconds for this response using
+ * the <code>setProperty</code> method intended to be used in
+ * forwarded or included servlets/JSPs.
+ * <P>
+ * If the expiration value is set to <code>0</code>, caching is disabled for this
+ * portlet; if the value is set to <code>-1</code>, the cache does not expire.
+ * <p>
+ * A default can be defined in the portlet deployment descriptor
+ * with the <code>expiration-cache<code> tag, otherwise it is <code>0</code>.
+ * <p>
+ * Non-integer values are treated as <code>0</code>.
+ * <p>
+ * The value is <code>"portlet.expiration-cache"</code>.
+ *
+ * @see CacheControl
+ */
+ public static final String EXPIRATION_CACHE = "portlet.expiration-cache";
+
+ /**
+ * Property to set the cache scope for this response using the
+ * <code>setProperty</code> method intended to be used in
+ * forwarded or included servlets/JSPs.
+ * <P>
+ * Predefined cache scopes are: <code>PUBLIC_SCOPE</code> and <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * A default can be defined in the portlet deployment descriptor
+ * with the <code>cache-scope<code> tag, otherwise it is <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * Values that are not either <code>PUBLIC_SCOPE</code> or <code>PRIVATE_SCOPE</code>
+ * are treated as <code>PRIVATE_SCOPE</code>.
+ * <p>
+ * The value is <code>"portlet.cache-scope"</code>.
+ *
+ * @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 <code>"portlet.public-scope"</code>.
+ *
+ * @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 <code>"portlet.private-scope"</code>.
+ *
+ * @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.
+ * <p>
+ * This property needs to be set using the <code>setProperty</code> method.
+ * <P>
+ * The value is <code>"portlet.ETag "</code>.
+ *
+ * @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 <code>setProperty</code> method with a non-null
+ * value and is intended to be used in forwarded or included servlets/JSPs.
+ * The value itself is not evaluated.
+ * <P>
+ * The value is <code>"portlet.use-cached-content "</code>.
+ *
+ * @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.
+ * <p>
+ * This property needs to be set using the <code>setProperty</code> method with a non-null
+ * value. The value itself is not evaluated.
+ * <p>
+ * The value is <code>"X-JAVAX-PORTLET-NAMESPACED-RESPONSE"</code>.
+ *
+ * @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.
+ * <p>
+ * Support for this property is optional and the portlet can verify if the
+ * calling portal supports this property via the <code>MARKUP_HEAD_ELEMENT_SUPPORT</code>
+ * property on the <code>PortalContext</code>.
+ * <p>
+ * 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.
+ * <p>
+ * This property needs to be set using the
+ * <code>setProperty(String key,org.w3c.dom.Element element)</code>
+ * method.
+ * <p>
+ * The value is <code>"javax.portlet.markup.head.element"</code>.
+ *
+ * @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.
+ * <p>
+ * If no content type was set previously using the {@link #setContentType}
+ * method this method returns <code>null</code>.
+ *
+ * @see #setContentType
+ *
+ * @return the MIME type of the response, or <code>null</code> 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
+ * the {@link PortletRequest#getResponseContentType} value is
+ * set as response content type by the portlet container.
+ * <p>
+ * Calling <code>setContentType</code> after <code>getWriter</code> or
+ * <code>getOutputStream</code> does not change the content type.
+ * <p>
+ *
+ * @param type
+ * the content MIME type
+ *
+ * @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.
+ *
+ * <p>
+ * See <a href="http://ds.internic.net/rfc/rfc2045.txt">RFC 2047</a> for
+ * more information about character encoding and MIME.
+ *
+ * @return a <code>String</code> specifying the name of the charset, for
+ * example, <code>ISO-8859-1</code>
+ *
+ */
+ public String getCharacterEncoding();
+
+ /**
+ * Returns a PrintWriter object that can send character text to the portal.
+ * <p>
+ * Before calling this method the content type of the render response should
+ * be set using the {@link #setContentType} method.
+ * <p>
+ * Either this method or {@link #getPortletOutputStream} may be called to
+ * write the body, not both.
+ *
+ * @return a <code>PrintWriter</code> 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 <code>getPortletOutputStream</code> 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.
+ * <p>
+ * 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 <code>IllegalStateException</code>.
+ *
+ * @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 <code>IllegalStateException</code>.
+ *
+ * @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
+ * <code>IllegalStateException</code>.
+ *
+ * @exception java.lang.IllegalStateException
+ * if the response has already been committed
+ *
+ * @see #setBufferSize
+ * @see #getBufferSize
+ * @see #flushBuffer
+ * @see #isCommitted
+ */
+ public void reset();
+
+ /**
+ * Returns a <code>OutputStream</code> suitable for writing binary data in
+ * the response. The portlet container does not encode the binary data.
+ * <p>
+ * Before calling this method the content type of the render response must
+ * be set using the {@link #setContentType} method.
+ * <p>
+ * Calling <code>flush()</code> on the OutputStream commits the response.
+ * <p>
+ * Either this method or {@link #getWriter} may be called to write the body,
+ * not both.
+ *
+ * @return a <code>OutputStream</code> for writing binary data
+ *
+ * @exception java.lang.IllegalStateException
+ * if the <code>getWriter</code> 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 portlet URL targeting the portlet. If no portlet mode, window
+ * state or security modifier is set in the PortletURL the current values
+ * are preserved. If a request is triggered by the PortletURL, it results in
+ * a render request.
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific
+ * parameters and portlet modes and window states.
+ * <p>
+ * The created URL will per default not contain any parameters of the
+ * current render request.
+ *
+ * @return a portlet render URL
+ */
+ public PortletURL createRenderURL();
+
+ /**
+ * Creates a portlet URL targeting the portlet. If no portlet mode, window
+ * state or security modifier is set in the PortletURL the current values
+ * are preserved. If a request is triggered by the PortletURL, it results in
+ * an action request.
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific
+ * parameters and portlet modes and window states.
+ * <p>
+ * The created URL will per default not contain any parameters of the
+ * current render request.
+ *
+ * @return a portlet action URL
+ */
+ public PortletURL createActionURL();
+
+ /**
+ * Creates a portlet URL targeting the portlet. If no security modifier is
+ * set in the PortletURL the current values are preserved. The current
+ * render parameters, portlet mode and window state are preserved.
+ * <p>
+ * If a request is triggered by the PortletURL, it results in a serve
+ * resource request of the <code>ResourceServingPortlet</code> interface.
+ * <p>
+ * The returned URL can be further extended by adding portlet-specific
+ * parameters .
+ * <p>
+ * The created URL will per default contain the current
+ * cacheability setting of the parent resource.
+ * If no parent resource is available, <code>PAGE</code> 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();
+
+
+
+
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortalContext.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortalContext.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortalContext.java
new file mode 100644
index 0000000..9fa9e98
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortalContext.java
@@ -0,0 +1,120 @@
+/* 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 <CODE>PortalContext</CODE> interface gives the portlet
+ * the ability to retrieve information about the portal calling this portlet.
+ * <p>
+ * The portlet can only read the <CODE>PortalContext</CODE> data.
+ */
+public interface PortalContext
+{
+ /**
+ * Property indicating if the portal application supports the
+ * <code>MimeResponse</code> property <code>MARKUP_HEAD_ELEMENT</code>.
+ * <p>
+ * A non-null value indicates that the portal application supports
+ * the <code>MARKUP_HEAD_ELEMENT</code> property.
+ * <p>
+ * The value is <code>"javax.portlet.markup.head.element.support"</code>.
+ *
+ * @since 2.0
+ */
+ public static final String MARKUP_HEAD_ELEMENT_SUPPORT = "javax.portlet.markup.head.element.support";
+
+
+ /**
+ * Returns the portal property with the given name,
+ * or a <code>null</code> if there is
+ * no property by that name.
+ *
+ * @param name property name
+ *
+ * @return portal property with key <code>name</code>
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public java.lang.String getProperty(java.lang.String name);
+
+
+ /**
+ * Returns all portal property names, or an empty
+ * <code>Enumeration</code> if there are no property names.
+ *
+ * @return All portal property names as an
+ * <code>Enumeration</code> of <code>String</code> objects
+ */
+ public java.util.Enumeration<String> getPropertyNames();
+
+
+ /**
+ * Returns all supported portlet modes by the portal
+ * as an enumeration of <code>PortletMode</code> objects.
+ * <p>
+ * The portlet modes must at least include the
+ * standard portlet modes <code>EDIT, HELP, VIEW</code>.
+ *
+ * @return All supported portal modes by the portal
+ * as an enumeration of <code>PortletMode</code> objects.
+ */
+
+ public java.util.Enumeration<PortletMode> getSupportedPortletModes();
+
+
+ /**
+ * Returns all supported window states by the portal
+ * as an enumeration of <code>WindowState</code> objects.
+ * <p>
+ * The window states must at least include the
+ * standard window states <code> MINIMIZED, NORMAL, MAXIMIZED</code>.
+ *
+ * @return All supported window states by the portal
+ * as an enumeration of <code>WindowState</code> objects.
+ */
+
+ public java.util.Enumeration<WindowState> getSupportedWindowStates();
+
+
+ /**
+ * Returns information about the portal like vendor, version, etc.
+ * <p>
+ * The form of the returned string is <I>servername/versionnumber</I>. For
+ * example, the reference implementation Pluto may return the string
+ * <CODE>Pluto/1.0</CODE>.
+ * <p>
+ * The portlet container may return other optional information after the
+ * primary string in parentheses, for example, <CODE>Pluto/1.0
+ * (JDK 1.3.1; Windows NT 4.0 x86)</CODE>.
+ *
+ * @return a <CODE>String</CODE> containing at least the portal name and version number
+ */
+
+ public java.lang.String getPortalInfo();
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/Portlet.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/Portlet.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/Portlet.java
new file mode 100644
index 0000000..9842ecf
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/Portlet.java
@@ -0,0 +1,186 @@
+/* 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.io.IOException;
+
+
+/**
+ * The <CODE>Portlet</CODE> interface is used by the portlet container to
+ * invoke the portlets. Every portlet has to implement this interface,
+ * either by directly implementing it, or by using an existing class
+ * implementing the Portlet interface.
+ * <P>
+ * A portlet is a Java technology-based web component. It is managed by the portlet container and
+ * processes requests and generates dynamic content as response. Portlets are used by portals as
+ * pluggable user interface components.
+ * <p>
+ * The content generated by a portlet is called a fragment. A fragment is a piece of
+ * markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated
+ * with other fragments into a complete document. The content of a portlet is normally
+ * aggregated with the content of other portlets into the portal page.
+ * <P>
+ * The portlet container instantiates portlets, manages their lifecycle
+ * and invoking them to process requests. The lifecycle consists of:
+ * <ul>
+ * <li>initializing the portlet using using the <code>init</code> method
+ * <li>request processsing
+ * <li>taking the portlet out of service using the <code>destroy</code> method
+ * </ul>
+ * <p>
+ * Request processing is divided into two types:
+ * <ul>
+ * <li>action requests handled through the <code>processAction</code> method,
+ * to perform actions targeted to the portlet
+ * <li>render requests handled through the <code>render</code> method,
+ * to perform the render operation
+ * </ul>
+ */
+public interface Portlet
+{
+
+
+ /**
+ * Called by the portlet container to indicate to a portlet that the
+ * portlet is being placed into service.
+ *
+ * <p>The portlet container calls the <code>init</code>
+ * method exactly once after instantiating the portlet.
+ * The <code>init</code> method must complete successfully
+ * before the portlet can receive any requests.
+ *
+ * <p>The portlet container cannot place the portlet into service
+ * if the <code>init</code> method
+ * <ol>
+ * <li>Throws a <code>PortletException</code>
+ * <li>Does not return within a time period defined by the portlet container.
+ * </ol>
+ *
+ *
+ * @param config a <code>PortletConfig</code> object
+ * containing the portlet's
+ * configuration and initialization parameters
+ *
+ * @exception PortletException if an exception has occurred that
+ * interferes with the portlet's normal
+ * operation.
+ * @exception UnavailableException if the portlet cannot perform the initialization at this time.
+ *
+ *
+ */
+
+ public void init(PortletConfig config) throws PortletException;
+
+
+
+
+ /**
+ * Called by the portlet container to allow the portlet to process
+ * an action request. This method is called if the client request was
+ * originated by a URL created (by the portlet) with the
+ * <code>RenderResponse.createActionURL()</code> method.
+ * <p>
+ * Typically, in response to an action request, a portlet updates state
+ * based on the information sent in the action request parameters.
+ * In an action the portlet may:
+ * <ul>
+ * <li>issue a redirect
+ * <li>change its window state
+ * <li>change its portlet mode
+ * <li>modify its persistent state
+ * <li>set render parameters
+ * </ul>
+ * <p>
+ * A client request triggered by an action URL translates into one
+ * action request and many render requests, one per portlet in the portal page.
+ * The action processing must be finished before the render requests
+ * can be issued.
+ *
+ * @param request
+ * the action request
+ * @param response
+ * the action response
+ * @exception PortletException
+ * if the portlet has problems fulfilling the
+ * request
+ * @exception UnavailableException
+ * if the portlet is unavailable to process the action at this time
+ * @exception PortletSecurityException
+ * if the portlet cannot fullfill this request because of security reasons
+ * @exception IOException
+ * if the streaming causes an I/O problem
+ */
+ public void processAction (ActionRequest request, ActionResponse response)
+ throws PortletException, java.io.IOException;
+
+
+
+ /**
+ * Called by the portlet container to allow the portlet to generate
+ * the content of the response based on its current state.
+ *
+ * @param request
+ * the render request
+ * @param response
+ * the render response
+ *
+ * @exception PortletException
+ * if the portlet has problems fulfilling the
+ * rendering request
+ * @exception UnavailableException
+ * if the portlet is unavailable to perform render at this time
+ * @exception PortletSecurityException
+ * if the portlet cannot fullfill this request because of security reasons
+ * @exception java.io.IOException
+ * if the streaming causes an I/O problem
+ */
+
+ public void render (RenderRequest request, RenderResponse response)
+ throws PortletException, java.io.IOException;
+
+
+ /**
+ *
+ * Called by the portlet container to indicate to a portlet that the
+ * portlet is being taken out of service.
+ * <p>
+ * Before the portlet container calls the destroy method, it should
+ * allow any threads that are currently processing requests within
+ * the portlet object to complete execution. To avoid
+ * waiting forever, the portlet container can optionally wait for
+ * a predefined time before destroying the portlet object.
+ *
+ * <p>This method enables the portlet to do the following:
+ * <ul>
+ * <li>clean up any resources that it holds (for example, memory,
+ * file handles, threads)
+ * <li>make sure that any persistent state is
+ * synchronized with the portlet current state in memory.
+ * </ul>
+ */
+
+ public void destroy();
+}
+
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletConfig.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletConfig.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletConfig.java
new file mode 100644
index 0000000..67874c1
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletConfig.java
@@ -0,0 +1,256 @@
+/* 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 <CODE>PortletConfig</CODE> interface provides the portlet with
+ * its configuration. The configuration holds information about the
+ * portlet that is valid for all users. The configuration is retrieved
+ * from the portlet definition in the deployment descriptor.
+ * The portlet can only read the configuration data.
+ * <p>
+ * The configuration information contains the portlet name, the portlet
+ * initialization parameters, the portlet resource bundle and the portlet
+ * application context.
+ *
+ * @see Portlet
+ */
+public interface PortletConfig
+{
+
+
+ /**
+ * Returns the name of the portlet.
+ * <P>
+ * The name may be provided via server administration, assigned in the
+ * portlet application deployment descriptor with the <code>portlet-name</code>
+ * tag.
+ *
+ * @return the portlet name
+ */
+
+ public String getPortletName ();
+
+
+ /**
+ * Returns the <code>PortletContext</code> of the portlet application
+ * the portlet is in.
+ *
+ * @return a <code>PortletContext</code> object, used by the
+ * caller to interact with its portlet container
+ *
+ * @see PortletContext
+ */
+
+ public PortletContext getPortletContext ();
+
+
+ /**
+ * Gets the resource bundle for the given locale based on the
+ * resource bundle defined in the deployment descriptor
+ * with <code>resource-bundle</code> tag or the inlined resources
+ * defined in the deployment descriptor.
+ *
+ * @param locale the locale for which to retrieve the resource bundle
+ *
+ * @return the resource bundle for the given locale
+ *
+ */
+
+ public java.util.ResourceBundle getResourceBundle(java.util.Locale locale);
+
+
+ /**
+ * Returns a String containing the value of the named initialization parameter,
+ * or null if the parameter does not exist.
+ *
+ * @param name a <code>String</code> specifying the name
+ * of the initialization parameter
+ *
+ * @return a <code>String</code> containing the value
+ * of the initialization parameter
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public String getInitParameter(java.lang.String name);
+
+
+ /**
+ * Returns the names of the portlet initialization parameters as an
+ * <code>Enumeration</code> of String objects, or an empty <code>Enumeration</code> if the
+ * portlet has no initialization parameters.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code>
+ * objects containing the names of the portlet
+ * initialization parameters, or an empty <code>Enumeration</code> if the
+ * portlet has no initialization parameters.
+ */
+
+ public java.util.Enumeration<String> getInitParameterNames();
+
+
+ /**
+ * Returns the names of the public render parameters supported by the portlet
+ * as an <code>Enumeration</code> of <code>String</code> objects,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined public render parameters.
+ * <p>
+ * Public render parameters are defined in the portlet deployment descriptor
+ * with the <code>supported-public-render-parameter</code> element.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code>
+ * objects containing the names of the public
+ * render parameters, or an empty <code>Enumeration</code> if the
+ * portlet has not defined support for any public render parameters
+ * in the portlet deployment descriptor.
+ * @since 2.0
+ */
+
+ public java.util.Enumeration<String> getPublicRenderParameterNames();
+
+
+ /**
+ * Returns the default namespace for events and public render parameters.
+ * This namespace is defined in the portlet deployment descriptor
+ * with the <code>default-namespace</code> element.
+ * <p>
+ * If no default namespace is defined in the portlet deployment
+ * descriptor this methods returns the XML default namespace
+ * <code>XMLConstants.NULL_NS_URI</code>.
+ *
+ * @return the default namespace defined in the portlet deployment
+ * descriptor, or <code>XMLConstants.NULL_NS_URI</code> is non is
+ * defined.
+ * @since 2.0
+ */
+ public java.lang.String getDefaultNamespace();
+
+
+ /**
+ * Returns the QNames of the publishing events supported by the portlet
+ * as an <code>Enumeration</code> of <code>QName</code> objects,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any publishing events.
+ * <p>
+ * Publishing events are defined in the portlet deployment descriptor
+ * with the <code>supported-publishing-event</code> element.
+ * <p>
+ * Note that this call does not return any events published that have not been
+ * declared in the deployment descriptor as supported.
+ * <p>
+ * If the event was defined using the <code>name</code> element instead of
+ * the <code>qname</code> element the defined default namespace
+ * is added as namespace for the returned QName.
+ *
+ * @return an <code>Enumeration</code> of <code>QName</code>
+ * objects containing the names of the publishing events,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any support for publishing events in
+ * the deployment descriptor.
+ * @since 2.0
+ */
+ public java.util.Enumeration<javax.xml.namespace.QName> getPublishingEventQNames();
+
+
+ /**
+ * Returns the QNames of the processing events supported by the portlet
+ * as an <code>Enumeration</code> of <code>QName</code> objects,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any processing events.
+ * <p>
+ * Processing events are defined in the portlet deployment descriptor
+ * with the <code>supported-processing-event</code> element.
+ * <p>
+ * If the event was defined using the <code>name</code> element instead of
+ * the <code>qname</code> element the defined default namespace
+ * is added as namespace for the returned QName.
+ *
+ * @return an <code>Enumeration</code> of <code>QName</code>
+ * objects containing the names of the processing events,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any support for processing events in
+ * the deployment descriptor.
+ * @since 2.0
+ */
+ public java.util.Enumeration<javax.xml.namespace.QName> getProcessingEventQNames();
+
+ /**
+ * Returns the locales supported by the portlet
+ * as an <code>Enumeration</code> of <code>Locale</code> objects,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any supported locales.
+ * <p>
+ * Supported locales are defined in the portlet deployment descriptor
+ * with the <code>supported-locale</code> element.
+ *
+ * @return an <code>Enumeration</code> of <code>Locale</code>
+ * objects containing the supported locales,
+ * or an empty <code>Enumeration</code> if the
+ * portlet has not defined any supported locales in
+ * the deployment descriptor.
+ * @since 2.0
+ */
+ public java.util.Enumeration<java.util.Locale> getSupportedLocales();
+
+ /**
+ * Returns the container runtime options
+ * and values for this portlet.
+ * <p>
+ * The portlet can set container runtime
+ * options in the <code>portlet.xml</code> via the
+ * <code>container-runtime-option</code> element with a name and a
+ * value on the application and portlet level.<br>
+ * If a container runtime option is set on the portlet application
+ * level and on the portlet level with the same name the setting
+ * on the portlet level takes precedence and overwrites the one
+ * set on the portal application level.
+ * <p>
+ * The map returned from this method will provide the subset the
+ * portlet container supports of the options the portlet has specified
+ * in the <code>portlet.xml</code>. Options that the portlet container
+ * does not support will not be returned in this map.
+ * <p>
+ * The map will contain name of the runtime option as key of type String
+ * and the runtime options as values of type String array (<code>String[]</code>)
+ * with the values specified in the <code>portlet.xml</code> deployment descriptor.
+ *
+ * @since 2.0
+ *
+ * @return an immutable <code>Map</code> containing portlet
+ * container runtime options names as keys and the
+ * container runtime values as map values, or an empty <code>Map</code>
+ * if no portlet container runtime options are set
+ * in the <code>portlet.xml</code> or supported by this portlet container.
+ * The keys in the map are of type String. The values in the map are of type
+ * String array (<code>String[]</code>).
+ */
+ public java.util.Map<String, String[]> getContainerRuntimeOptions();
+}
+
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletContext.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletContext.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletContext.java
new file mode 100644
index 0000000..8190c4a
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletContext.java
@@ -0,0 +1,469 @@
+/* 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.net.MalformedURLException;
+
+
+
+
+/**
+ * The <CODE>PortletContext</CODE> interface defines a portlet view
+ * of the portlet container.
+ * The <CODE>PortletContext</CODE> also makes resources available
+ * to the portlet. Using the context, a portlet can access
+ * the portlet log, and obtain URL references to resources.
+ *
+ * <p>There is one context per "portlet application" per Java Virtual Machine. (A
+ * "portlet application" is a collection of portlets, servlets, and content installed
+ * under a specific subset of the server URL namespace, such as <code>/catalog</code>.
+ * They are possibly installed via a <code>.war</code> file.)
+ * As a web application, a portlet application also has a servlet context.
+ * The portlet context leverages most of its functionality from the
+ * servlet context of the portlet application.
+ * <p>
+ * Attributes stored in the context are global for <I>all</I> users and <I>all</I>
+ * components in the portlet application.
+ * <p>
+ * In the case of a web
+ * application marked "distributed" in its deployment descriptor, there will
+ * be one context instance for each virtual machine. In this situation, the
+ * context cannot be used as a location to share global information (because
+ * the information is not truly global). Use an external resource, such as
+ * a database to achieve sharing on a global scope.
+ */
+public interface PortletContext
+{
+
+ /**
+ * Returns the name and version of the portlet container in which the
+ * portlet is running.
+ *
+ * <P>
+ * The form of the returned string is <code>containername/versionnumber</code>.
+ *
+ *
+ * @return the string containing at least name and version number
+ */
+
+ public String getServerInfo ();
+
+ /**
+ * Returns a {@link PortletRequestDispatcher} object that acts
+ * as a wrapper for the resource located at the given path.
+ * A <code>PortletRequestDispatcher</code> object can be used include the
+ * resource in a response. The resource can be dynamic or static.
+ *
+ * <p>The pathname must begin with a slash (<code> / </code>) and is interpreted as relative
+ * to the current context root.
+ *
+ * <p>This method returns <code>null</code> if the <code>PortletContext</code>
+ * cannot return a <code>PortletRequestDispatcher</code>
+ * for any reason.
+ *
+ *
+ * @param path a <code>String</code> specifying the pathname
+ * to the resource
+ * @return a <code>PortletRequestDispatcher</code> object
+ * that acts as a wrapper for the resource
+ * at the specified path.
+ * @see PortletRequestDispatcher
+ */
+
+ public PortletRequestDispatcher getRequestDispatcher(String path);
+
+
+
+ /**
+ * Returns a {@link PortletRequestDispatcher} object that acts
+ * as a wrapper for the named servlet.
+ *
+ * <p>Servlets (and also JSP pages) may be given names via server
+ * administration or via a web application deployment descriptor.
+ *
+ * <p>This method returns <code>null</code> if the
+ * <code>PortletContext</code> cannot return a
+ * <code>PortletRequestDispatcher</code> for any reason.
+ *
+ *
+ * @param name a <code>String</code> specifying the name
+ * of a servlet to be wrapped
+ *
+ * @return a <code>PortletRequestDispatcher</code> object
+ * that acts as a wrapper for the named servlet
+ *
+ * @see PortletRequestDispatcher
+ *
+ */
+
+ public PortletRequestDispatcher getNamedDispatcher(String name);
+
+
+ /**
+ * Returns the resource located at the given path as an InputStream object.
+ * The data in the InputStream can be of any type or length. The method returns
+ * null if no resource exists at the given path.
+ * <p>
+ * In order to access protected resources the path has to be prefixed with
+ * <code>/WEB-INF/</code> (for example <code>/WEB-INF/myportlet/myportlet.jsp</code>).
+ * Otherwise, the direct path is used
+ * (for example <code>/myportlet/myportlet.jsp</code>).
+ *
+ * @param path the path to the resource
+ *
+ * @return the input stream
+ */
+ public java.io.InputStream getResourceAsStream (String path);
+
+
+
+ /**
+ * Returns the major version of the Portlet API that this portlet
+ * container supports.
+ *
+ * @return the major version
+ *
+ * @see #getMinorVersion()
+ */
+
+ public int getMajorVersion ();
+
+
+ /**
+ * Returns the minor version of the Portlet API that this portlet
+ * container supports.
+ *
+ * @return the minor version
+ *
+ * @see #getMajorVersion()
+ */
+
+ public int getMinorVersion ();
+
+
+ /**
+ * Returns the MIME type of the specified file, or <code>null</code> if
+ * the MIME type is not known. The MIME type is determined
+ * by the configuration of the portlet container and may be specified
+ * in a web application deployment descriptor. Common MIME
+ * types are <code>text/html</code> and <code>image/gif</code>.
+ *
+ *
+ * @param file a <code>String</code> specifying the name
+ * of a file
+ *
+ * @return a <code>String</code> specifying the MIME type of the file
+ *
+ */
+
+ public String getMimeType(String file);
+
+
+ /**
+ * Returns a <code>String</code> containing the real path
+ * for a given virtual path. For example, the path <code>/index.html</code>
+ * returns the absolute file path of the portlet container file system.
+ *
+ * <p>The real path returned will be in a form
+ * appropriate to the computer and operating system on
+ * which the portlet container is running, including the
+ * proper path separators. This method returns <code>null</code>
+ * if the portlet container cannot translate the virtual path
+ * to a real path for any reason (such as when the content is
+ * being made available from a <code>.war</code> archive).
+ *
+ * @param path a <code>String</code> specifying a virtual path
+ *
+ * @return a <code>String</code> specifying the real path,
+ * or null if the transformation cannot be performed.
+ */
+
+ public String getRealPath(String path);
+
+
+ /**
+ * Returns a directory-like listing of all the paths to resources within
+ * the web application longest sub-path of which
+ * matches the supplied path argument. Paths indicating subdirectory paths
+ * end with a slash (<code>/</code>). The returned paths are all
+ * relative to the root of the web application and have a leading slash.
+ * For example, for a web application
+ * containing<br><br>
+ * <code>
+ * /welcome.html<br>
+ * /catalog/index.html<br>
+ * /catalog/products.html<br>
+ * /catalog/offers/books.html<br>
+ * /catalog/offers/music.html<br>
+ * /customer/login.jsp<br>
+ * /WEB-INF/web.xml<br>
+ * /WEB-INF/classes/com.acme.OrderPortlet.class,<br><br>
+ * </code>
+ *
+ * <code>getResourcePaths("/")</code> returns
+ * <code>{"/welcome.html", "/catalog/", "/customer/", "/WEB-INF/"}</code><br>
+ * <code>getResourcePaths("/catalog/")</code> returns
+ * <code>{"/catalog/index.html", "/catalog/products.html", "/catalog/offers/"}</code>.<br>
+ *
+ * @param path
+ * the partial path used to match the resources, which must start with a slash
+ * @return a Set containing the directory listing, or <code>null</code> if there
+ * are no resources in the web application of which the path
+ * begins with the supplied path.
+ */
+
+ public java.util.Set<String> getResourcePaths(String path);
+
+
+
+ /**
+ * Returns a URL to the resource that is mapped to a specified
+ * path. The path must begin with a slash (<code>/</code>) and is interpreted
+ * as relative to the current context root.
+ *
+ * <p>This method allows the portlet container to make a resource
+ * available to portlets from any source. Resources
+ * can be located on a local or remote
+ * file system, in a database, or in a <code>.war</code> file.
+ *
+ * <p>The portlet container must implement the URL handlers
+ * and <code>URLConnection</code> objects that are necessary
+ * to access the resource.
+ *
+ * <p>This method returns <code>null</code>
+ * if no resource is mapped to the pathname.
+ *
+ * <p>Some containers may allow writing to the URL returned by
+ * this method using the methods of the URL class.
+ *
+ * <p>The resource content is returned directly, so be aware that
+ * requesting a <code>.jsp</code> page returns the JSP source code.
+ * Use a <code>RequestDispatcher</code> instead to include results of
+ * an execution.
+ *
+ * <p>This method has a different purpose than
+ * <code>java.lang.Class.getResource</code>,
+ * which looks up resources based on a class loader. This
+ * method does not use class loaders.
+ *
+ * @param path a <code>String</code> specifying
+ * the path to the resource
+ *
+ * @return the resource located at the named path,
+ * or <code>null</code> if there is no resource
+ * at that path
+ *
+ * @exception MalformedURLException if the pathname is not given in
+ * the correct form
+ *
+ */
+
+ public java.net.URL getResource(String path) throws java.net.MalformedURLException;
+
+
+ /**
+ * Returns the portlet container attribute with the given name,
+ * or null if there is no attribute by that name.
+ * An attribute allows a portlet container to give the
+ * portlet additional information not
+ * already provided by this interface.
+ * A list of supported attributes can be retrieved using
+ * <code>getAttributeNames</code>.
+ *
+ * <p>The attribute is returned as a <code>java.lang.Object</code>
+ * or some subclass.
+ * Attribute names should follow the same convention as package
+ * names. The Java Portlet API specification reserves names
+ * matching <code>java.*</code>, <code>javax.*</code>,
+ * and <code>sun.*</code>.
+ *
+ *
+ * @param name a <code>String</code> specifying the name
+ * of the attribute
+ *
+ * @return an <code>Object</code> containing the value
+ * of the attribute, or <code>null</code>
+ * if no attribute exists matching the given
+ * name
+ *
+ * @see #getAttributeNames
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public java.lang.Object getAttribute(java.lang.String name);
+
+
+ /**
+ * Returns an <code>Enumeration</code> containing the attribute names
+ * available within this portlet context, or an empty
+ * <code>Enumeration</code> if no attributes are available. Use the
+ * {@link #getAttribute} method with an attribute name
+ * to get the value of an attribute.
+ *
+ * @return an <code>Enumeration</code> of attribute names
+ *
+ * @see #getAttribute
+ */
+
+ public java.util.Enumeration<String> getAttributeNames();
+
+
+ /**
+ * Returns a String containing the value of the named context-wide
+ * initialization parameter, or <code>null</code> if the parameter does not exist.
+ * This method provides configuration information which may be useful for
+ * an entire "portlet application".
+ *
+ * @param name a <code>String</code> containing the name of the
+ * requested parameter
+ *
+ * @return a <code>String</code> containing the value
+ * of the initialization parameter, or
+ * <code>null</code> if the parameter does not exist.
+ *
+ * @see #getInitParameterNames
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public java.lang.String getInitParameter(java.lang.String name);
+
+
+ /**
+ * Returns the names of the context initialization parameters as an
+ * <code>Enumeration</code> of String objects, or an empty Enumeration if the context
+ * has no initialization parameters.
+ *
+ * @return an <code>Enumeration</code> of <code>String</code>
+ * objects containing the names of the context
+ * initialization parameters
+ *
+ * @see #getInitParameter
+ */
+
+ public java.util.Enumeration<String> getInitParameterNames();
+
+
+ /**
+ * Writes the specified message to a portlet log file, usually an event log.
+ * The name and type of the portlet log file is specific to the portlet container.
+ * <p>
+ * This method mapps to the <code>ServletContext.log</code> method.
+ * The portlet container may in addition log this message in a
+ * portlet container specific log file.
+ *
+ * @param msg a <code>String</code> specifying the
+ * message to be written to the log file
+ */
+
+ public void log(java.lang.String msg);
+
+
+ /**
+ * Writes an explanatory message and a stack trace for a given
+ * Throwable exception to the portlet log file.
+ * The name and type of the portlet log file is specific to the
+ * portlet container, usually an event log.
+ * <p>
+ * This method is mapped to the <code>ServletContext.log</code> method.
+ * The portlet container may in addition log this message in a
+ * portlet container specific log file.
+ *
+ * @param message a <code>String</code> that
+ * describes the error or exception
+ * @param throwable the <code>Throwable</code> error
+ * or exception
+ */
+
+ public void log(java.lang.String message, java.lang.Throwable throwable);
+
+
+ /**
+ * Removes the attribute with the given name from the portlet context.
+ * After removal, subsequent calls to
+ * {@link #getAttribute} to retrieve the attribute's value
+ * will return <code>null</code>.
+ *
+ * @param name a <code>String</code> specifying the name
+ * of the attribute to be removed
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public void removeAttribute(java.lang.String name);
+
+
+ /**
+ * Binds an object to a given attribute name in this portlet context.
+ * If the name specified is already used for an attribute, this method
+ * removes the old attribute and binds the name to the new attribute.
+ * <p>
+ * If a null value is passed, the effect is the same as calling
+ * <code>removeAttribute()</code>.
+ *
+ * <p>Attribute names should follow the same convention as package
+ * names. The Java Portlet API specification reserves names
+ * matching <code>java.*</code>, <code>javax.*</code>, and
+ * <code>sun.*</code>.
+ *
+ * @param name a <code>String</code> specifying the name
+ * of the attribute
+ * @param object an <code>Object</code> representing the
+ * attribute to be bound
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if name is <code>null</code>.
+ */
+
+ public void setAttribute(java.lang.String name, java.lang.Object object);
+
+
+ /**
+ * Returns the name of this portlet application correponding to this PortletContext as specified
+ * in the <code>web.xml</code> deployment descriptor for this web application by the
+ * <code>display-name</code> element.
+ *
+ *
+ * @return The name of the web application or null if no name has been declared in the deployment descriptor.
+ */
+
+ public String getPortletContextName();
+
+
+ /**
+ * Returns the container container runtime options
+ * keys supported by this portlet container.
+ *
+ * @since 2.0
+ *
+ * @return container runtime options keys supported by this
+ * container as String values.
+ */
+ public java.util.Enumeration<String> getContainerRuntimeOptions();
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletException.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletException.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletException.java
new file mode 100644
index 0000000..83804ba
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletException.java
@@ -0,0 +1,97 @@
+/* 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 <CODE>PortletException</CODE> class defines a general exception
+ * that a portlet can throw when it is unable to perform its operation
+ * successfully.
+ */
+
+public class PortletException extends java.lang.Exception
+{
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constructs a new portlet exception.
+ */
+
+ public PortletException ()
+ {
+ super();
+ }
+
+ /**
+ * Constructs a new portlet exception with the given text. The
+ * portlet container may use the text write it to a log.
+ *
+ * @param text
+ * the exception text
+ */
+
+ public PortletException (String text)
+ {
+ super (text);
+ }
+
+ /**
+ * Constructs a new portlet exception when the portlet needs to do
+ * the following:
+ * <ul>
+ * <li>throw an exception
+ * <li>include the "root cause" exception
+ * <li>include a description message
+ * </ul>
+ *
+ * @param text
+ * the exception text
+ * @param cause
+ * the root cause
+ */
+
+ public PortletException (String text, Throwable cause)
+ {
+ super(text, cause);
+ }
+
+ /**
+ * Constructs a new portlet exception when the portlet needs to throw an
+ * exception. The exception's message is based on the localized message
+ * of the underlying exception.
+ *
+ * @param cause
+ * the root cause
+ */
+
+ public PortletException (Throwable cause)
+ {
+ super(cause);
+ }
+
+
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletMode.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletMode.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletMode.java
new file mode 100644
index 0000000..33260c1
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletMode.java
@@ -0,0 +1,156 @@
+/* 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.Locale;
+
+
+/**
+ * The <CODE>PortletMode</CODE> class represents
+ * the possible modes that a portlet can assume.
+ * <P>
+ * A portlet mode indicates the function a portlet is performing.
+ * Normally, portlets perform different tasks and create different
+ * content depending on the function they are currently performing.
+ * When invoking a portlet, the portlet container provides the
+ * current portlet mode to the portlet.
+ * <p>
+ * Portlets can programmatically change their portlet
+ * mode when processing an action request.
+ * <P>
+ * This class defines the default portlet modes <code>EDIT, HELP, VIEW</code>.
+ * Additional portlet modes may be defined by calling the constructor
+ * of this class. If a portal/portlet-container does not support a
+ * custom portlet mode defined in the portlet application deployment descriptor,
+ * the custom portlet mode will be ignored by the portal/portlet container.
+ */
+public class PortletMode
+{
+
+ /**
+ * The expected functionality for a portlet in <code>VIEW</code> portlet mode
+ * is to generate markup reflecting the current state of the portlet.
+ * For example, the <code>VIEW</code> portlet mode of a portlet may
+ * include one or more screens that the user can navigate and interact
+ * with, or it may consist of static content that does not require any
+ * user interaction.
+ * <P>
+ * This mode must be supported by the portlet.
+ * <p>
+ * The string value for this mode is <code>"view"</code>.
+ */
+ public final static PortletMode VIEW = new PortletMode ("view");
+
+ /**
+ * Within the <code>EDIT</code> portlet mode, a portlet should provide
+ * content and logic that lets a user customize the behavior of the portlet.
+ * The EDIT portlet mode may include one or more screens among which
+ * users can navigate to enter their customization data.
+ * <p>
+ * Typically, portlets in <code>EDIT</code> portlet mode will
+ * set or update portlet preferences.
+ * <P>
+ * This mode is optional.
+ * <p>
+ * The string value for this mode is <code>"edit"</code>.
+ */
+ public final static PortletMode EDIT = new PortletMode ("edit");
+
+ /**
+ * When in <code>HELP</code> portlet mode, a portlet should provide help
+ * information about the portlet. This help information could be
+ * a simple help screen explaining the entire portlet in
+ * coherent text or it could be context-sensitive help.
+ * <P>
+ * This mode is optional.
+ * <p>
+ * The string value for this mode is <code>"help"</code>.
+ */
+ public final static PortletMode HELP = new PortletMode ("help");
+
+
+
+
+ private String _name;
+
+
+ /**
+ * Creates a new portlet mode with the given name.
+ * <p>
+ * Upper case letters in the name are converted to
+ * lower case letters.
+ *
+ * @param name The name of the portlet mode
+ */
+ public PortletMode(String name) {
+ if (name==null) {
+ throw new IllegalArgumentException("PortletMode name can not be NULL");
+ }
+ _name = name.toLowerCase(Locale.ENGLISH);
+ }
+
+
+ /**
+ * Returns a String representation of this portlet mode.
+ * Portlet mode names are always lower case names.
+ *
+ * @return String representation of this portlet mode
+ */
+
+ public String toString() {
+ return _name;
+ }
+
+ /**
+ * Returns the hash code value for this portlet mode.
+ * The hash code is constructed by producing the
+ * hash value of the String value of this mode.
+ *
+ * @return hash code value for this portlet mode
+ */
+
+ public int hashCode() {
+ return _name.hashCode();
+ }
+
+ /**
+ * Compares the specified object with this portlet mode
+ * for equality. Returns <code>true</code> if the
+ * Strings <code>equals</code> method for the String
+ * representing the two portlet modes returns <code>true</code>.
+ *
+ * @param object the portlet mode to compare this portlet mode with
+ *
+ * @return true, if the specified object is equal with this portlet mode
+ */
+
+ public boolean equals(Object object) {
+ if ( object instanceof PortletMode )
+ return _name.equals(((PortletMode) object)._name);
+ else
+ return false;
+ }
+}
+
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletModeException.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletModeException.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletModeException.java
new file mode 100644
index 0000000..b0023b8
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletModeException.java
@@ -0,0 +1,109 @@
+/* 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 <CODE>PortletModeException</CODE> is thrown when a portlet
+ * tries to use or set a portlet mode that is not supported by the current
+ * runtime environment or the portlet.
+ */
+
+public class PortletModeException extends PortletException
+{
+
+ private transient PortletMode _mode = null;
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constructs a new portlet mode exception with the given text and the
+ * portlet mode that caused this exception. The
+ * portlet container may use the text and portlet mode write it to a log.
+ *
+ * @param text
+ * the exception text
+ * @param mode
+ * the mode causing the exception
+ */
+
+ public PortletModeException (String text, PortletMode mode)
+ {
+ super (text);
+ _mode = mode;
+ }
+
+ /**
+ * Constructs a new portlet mode exception when the portlet needs to do
+ * the following:
+ * <ul>
+ * <li>throw an exception
+ * <li>include a message about the "root cause" that interfered
+ * with its normal operation
+ * <li>include a description message
+ * <li>include the portlet mode that caused this exception
+ * </ul>
+ *
+ * @param text
+ * the exception text
+ * @param cause
+ * the root cause
+ * @param mode
+ * the mode causing the exception
+ */
+
+ public PortletModeException (String text, Throwable cause, PortletMode mode)
+ {
+ super(text, cause);
+ _mode = mode;
+ }
+
+ /**
+ * Constructs a new portlet mode exception when the portlet needs to throw an
+ * exception. The exception message is based on the localized message
+ * of the underlying exception and the portlet mode that caused this exception.
+ *
+ * @param cause
+ * the root cause
+ * @param mode
+ * the mode causing the exception
+ */
+
+ public PortletModeException (Throwable cause, PortletMode mode)
+ {
+ super(cause);
+ _mode = mode;
+ }
+
+ /**
+ * Returns the unsupported portlet mode causing this exception.
+ *
+ * @return the portlet mode that caused this exception
+ */
+
+ public PortletMode getMode()
+ {
+ return _mode;
+ }
+}
http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/f0a1530f/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletPreferences.java
----------------------------------------------------------------------
diff --git a/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletPreferences.java b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletPreferences.java
new file mode 100644
index 0000000..e6a92a9
--- /dev/null
+++ b/portlet-api_2.0_spec/src/main/java/javax/portlet/PortletPreferences.java
@@ -0,0 +1,280 @@
+/* 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 <CODE>PortletPreferences</CODE> interface allows the portlet to store
+ * configuration data. It is not the
+ * purpose of this interface to replace general purpose databases.
+ * <p>
+ * There are two different types of preferences:
+ * <ul>
+ * <li>modifiable preferences - these preferences can be changed by the
+ * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
+ * Per default every preference is modifiable.
+ * <li>read-only preferences - these preferences cannot be changed by the
+ * portlet in any standard portlet mode, but may be changed by administrative modes.
+ * Preferences are read-only, if the are defined in the
+ * deployment descriptor with <code>read-only</code> set to <code>true</code>,
+ * or if the portlet container restricts write access.
+ * </ul>
+ * <p>
+ * Changes are persisted when the <code>store</code> method is called. The <code>store</code> method
+ * can only be invoked within the scope of a <code>processAction</code> call.
+ * Changes that are not persisted are discarded when the
+ * <code>processAction</code> or <code>render</code> method ends.
+ */
+public interface PortletPreferences
+{
+
+
+
+ /**
+ * Returns true, if the value of this key is defined as read-only and thus
+ * cannot be modified by the user.
+ * <p>
+ * Modifiable preferences can be changed by the
+ * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
+ * Per default every preference is modifiable.
+ * <p>
+ * Read-only preferences cannot be changed by the
+ * portlet in any standard portlet mode, but inside of custom modes,
+ * like the <code>CONFIG</code> mode, it may be allowed changing them.
+ * <p>
+ * Preferences are read-only, if they are defined in the
+ * deployment descriptor with <code>read-only</code> set to <code>true</code>,
+ * or if the portlet container restricts write access.
+ * <p>
+ * Note that even if this call returns <code>false</code> and the
+ * preference key is modifiable in general it does not mean that it
+ * is modifiable in the scope of the current request, e.g. if this
+ * request is a render request.
+ *
+ * @return false, if the value of this key can be changed, or
+ * if the key is not known
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if <code>key</code> is <code>null</code>.
+ */
+ public boolean isReadOnly(String key);
+
+
+
+ /**
+ * Returns the first String value associated with the specified key of this preference.
+ * If there is one or more preference values associated with the given key
+ * it returns the first associated value.
+ * If there are no preference values associated with the given key, or the
+ * backing preference database is unavailable, it returns the given
+ * default value.
+ * A <code>null</code> value is treated as a non-existent value.
+ *
+ * @param key key for which the associated value is to be returned
+ * @param def the value to be returned in the event that there is no
+ * value available associated with this <code>key</code>.
+ *
+ * @return the value associated with <code>key</code>, or <code>def</code>
+ * if no value is associated with <code>key</code>, or the backing
+ * store is inaccessible.
+ *
+ * @exception java.lang.IllegalArgumentException
+ * if <code>key</code> is <code>null</code>. (A
+ * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
+ *
+ * @see #getValues(String, String[])
+ */
+ public String getValue(String key, String def);
+
+
+ /**
+ * Returns the String array value associated with the specified key in this preference.
+ *
+ * <p>Returns the specified default if there is no value
+ * associated with the key, or if the backing store is inaccessible.
+ * A <code>null</code> value is treated as a non-existent value.
+ *
+ * <p>If the implementation supports <i>stored defaults</i> and such a
+ * default exists and is accessible, it is used in favor of the
+ * specified default.
+ *
+ *
+ * @param key key for which associated value is to be returned.
+ * @param def the value to be returned in the event that this
+ * preference node has no value associated with <code>key</code>
+ * or the associated value cannot be interpreted as a String array,
+ * or the backing store is inaccessible.
+ *
+ * @return the String array value associated with
+ * <code>key</code>, or <code>def</code> if the
+ * associated value does not exist.
+ *
+ * @exception java.lang.IllegalArgumentException if <code>key</code> is <code>null</code>. (A
+ * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
+ *
+ * @see #getValue(String,String)
+ */
+
+ public String[] getValues(String key, String[] def);
+
+
+
+ /**
+ * Associates the specified String value with the specified key in this
+ * preference.
+ * <p>
+ * The key cannot be <code>null</code>, but <code>null</code> values
+ * for the value parameter are allowed.
+ * <p>
+ * If the same key contained already a <code>String</code> or <code>String[]</code>
+ * value it must be replaced by the new value.
+ *
+ * @param key key with which the specified value is to be associated.
+ * @param value value to be associated with the specified key.
+ *
+ * @exception ReadOnlyException
+ * if this preference cannot be modified for this request
+ * @exception java.lang.IllegalArgumentException if key is <code>null</code>,
+ * or <code>key.length()</code>
+ * or <code>value.length</code> are to long. The maximum length
+ * for key and value are implementation specific.
+ *
+ * @see #setValues(String, String[])
+ */
+ public void setValue(String key, String value) throws ReadOnlyException;
+
+
+
+
+ /**
+ * Associates the specified String array value with the specified key in this
+ * preference.
+ * <p>
+ * The key cannot be <code>null</code>, but <code>null</code> values
+ * in the values parameter are allowed.
+ * <p>
+ * If the same key contained already a <code>String</code> or <code>String[]</code>
+ * value it must be replaced by the new value.
+ *
+ * @param key key with which the value is to be associated
+ * @param values values to be associated with key
+ *
+ * @exception java.lang.IllegalArgumentException if key is <code>null</code>, or
+ * <code>key.length()</code>
+ * is to long or <code>value.size</code> is to large. The maximum
+ * length for key and maximum size for value are implementation specific.
+ * @exception ReadOnlyException
+ * if this preference cannot be modified for this request
+ *
+ * @see #setValue(String,String)
+ */
+
+ public void setValues(String key, String[] values) throws ReadOnlyException;
+
+
+ /**
+ * Returns all of the keys that have an associated value,
+ * or an empty <code>Enumeration</code> if no keys are
+ * available.
+ *
+ * @return an Enumeration of the keys that have an associated value,
+ * or an empty <code>Enumeration</code> if no keys are
+ * available.
+ */
+ public java.util.Enumeration<String> getNames();
+
+ /**
+ * Returns a <code>Map</code> of the preferences.
+ * <p>
+ * The values in the returned <code>Map</code> are from type
+ * String array (<code>String[]</code>).
+ * <p>
+ * If no preferences exist this method returns an empty <code>Map</code>.
+ *
+ * @return an immutable <code>Map</code> containing preference names as
+ * keys and preference values as map values, or an empty <code>Map</code>
+ * if no preference exist. The keys in the preference
+ * map are of type String. The values in the preference map are of type
+ * String array (<code>String[]</code>).
+ */
+
+ public java.util.Map<String, String[]> getMap();
+
+
+ /**
+ * Resets or removes the value associated with the specified key.
+ * <p>
+ * If this implementation supports stored defaults, and there is such
+ * a default for the specified preference, the given key will be
+ * reset to the stored default.
+ * <p>
+ * If there is no default available the key will be removed.
+ *
+ * @param key to reset
+ *
+ * @exception java.lang.IllegalArgumentException if key is <code>null</code>.
+ * @exception ReadOnlyException
+ * if this preference cannot be modified for this request
+ */
+
+ public void reset(String key) throws ReadOnlyException;
+
+
+ /**
+ * Commits all changes made to the preferences via the
+ * <code>set</code> methods in the persistent store.
+ * <P>
+ * If this call returns successful, all changes are made
+ * persistent. If this call fails, no changes are made
+ * in the persistent store. This call is an atomic operation
+ * regardless of how many preference attributes have been modified.
+ * <P>
+ * All changes made to preferences not followed by a call
+ * to the <code>store</code> method are discarded when the
+ * portlet finishes the <code>processAction</code> method.
+ * <P>
+ * If a validator is defined for this preferences in the
+ * deployment descriptor, this validator is called before
+ * the actual store is performed to check whether the given
+ * preferences are valid. If this check fails a
+ * <code>ValidatorException</code> is thrown.
+ *
+ * @exception java.io.IOException
+ * if changes cannot be written into
+ * the backend store
+ * @exception ValidatorException
+ * if the validation performed by the
+ * associated validator fails
+ * @exception java.lang.IllegalStateException
+ * if this method is called inside a render call
+ *
+ * @see PreferencesValidator
+ */
+
+ public void store() throws java.io.IOException, ValidatorException;
+
+
+}