Return-Path: X-Original-To: apmail-portals-pluto-scm-archive@www.apache.org Delivered-To: apmail-portals-pluto-scm-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 14D2A17D2E for ; Tue, 27 Jan 2015 16:26:41 +0000 (UTC) Received: (qmail 91170 invoked by uid 500); 27 Jan 2015 16:26:41 -0000 Delivered-To: apmail-portals-pluto-scm-archive@portals.apache.org Received: (qmail 90994 invoked by uid 500); 27 Jan 2015 16:26:41 -0000 Mailing-List: contact pluto-scm-help@portals.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list pluto-scm@portals.apache.org Received: (qmail 90843 invoked by uid 99); 27 Jan 2015 16:26:41 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 27 Jan 2015 16:26:41 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 82C6EE0E27; Tue, 27 Jan 2015 16:26:39 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: msnicklous@apache.org To: pluto-scm@portals.apache.org Date: Tue, 27 Jan 2015 16:26:47 -0000 Message-Id: <908433fadfa64a93b3336817625c95b5@git.apache.org> In-Reply-To: <2ff2b89915144a5aaf762ff2efecf7d4@git.apache.org> References: <2ff2b89915144a5aaf762ff2efecf7d4@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [09/12] portals-pluto git commit: Modified name of portlet API module & moved artifact version to 3.0-snapshot in preparation for further prototyping http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/4fc38552/portlet-api/src/main/java/javax/portlet/PortletMode.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletMode.java b/portlet-api/src/main/java/javax/portlet/PortletMode.java new file mode 100644 index 0000000..33260c1 --- /dev/null +++ b/portlet-api/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 PortletMode class represents + * the possible modes that a portlet can assume. + *

+ * 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. + *

+ * Portlets can programmatically change their portlet + * mode when processing an action request. + *

+ * This class defines the default portlet modes EDIT, HELP, VIEW. + * 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 VIEW portlet mode + * is to generate markup reflecting the current state of the portlet. + * For example, the VIEW 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. + *

+ * This mode must be supported by the portlet. + *

+ * The string value for this mode is "view". + */ + public final static PortletMode VIEW = new PortletMode ("view"); + + /** + * Within the EDIT 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. + *

+ * Typically, portlets in EDIT portlet mode will + * set or update portlet preferences. + *

+ * This mode is optional. + *

+ * The string value for this mode is "edit". + */ + public final static PortletMode EDIT = new PortletMode ("edit"); + + /** + * When in HELP 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. + *

+ * This mode is optional. + *

+ * The string value for this mode is "help". + */ + public final static PortletMode HELP = new PortletMode ("help"); + + + + + private String _name; + + + /** + * Creates a new portlet mode with the given name. + *

+ * 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 true if the + * Strings equals method for the String + * representing the two portlet modes returns true. + * + * @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/4fc38552/portlet-api/src/main/java/javax/portlet/PortletModeException.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletModeException.java b/portlet-api/src/main/java/javax/portlet/PortletModeException.java new file mode 100644 index 0000000..b0023b8 --- /dev/null +++ b/portlet-api/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 PortletModeException 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: + *

    + *
  • throw an exception + *
  • include a message about the "root cause" that interfered + * with its normal operation + *
  • include a description message + *
  • include the portlet mode that caused this exception + *
+ * + * @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/4fc38552/portlet-api/src/main/java/javax/portlet/PortletPreferences.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletPreferences.java b/portlet-api/src/main/java/javax/portlet/PortletPreferences.java new file mode 100644 index 0000000..e6a92a9 --- /dev/null +++ b/portlet-api/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 PortletPreferences interface allows the portlet to store + * configuration data. It is not the + * purpose of this interface to replace general purpose databases. + *

+ * There are two different types of preferences: + *

    + *
  • modifiable preferences - these preferences can be changed by the + * portlet in any standard portlet mode (EDIT, HELP, VIEW). + * Per default every preference is modifiable. + *
  • 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 read-only set to true, + * or if the portlet container restricts write access. + *
+ *

+ * Changes are persisted when the store method is called. The store method + * can only be invoked within the scope of a processAction call. + * Changes that are not persisted are discarded when the + * processAction or render 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. + *

+ * Modifiable preferences can be changed by the + * portlet in any standard portlet mode (EDIT, HELP, VIEW). + * Per default every preference is modifiable. + *

+ * Read-only preferences cannot be changed by the + * portlet in any standard portlet mode, but inside of custom modes, + * like the CONFIG mode, it may be allowed changing them. + *

+ * Preferences are read-only, if they are defined in the + * deployment descriptor with read-only set to true, + * or if the portlet container restricts write access. + *

+ * Note that even if this call returns false 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 key is null. + */ + 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 null 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 key. + * + * @return the value associated with key, or def + * if no value is associated with key, or the backing + * store is inaccessible. + * + * @exception java.lang.IllegalArgumentException + * if key is null. (A + * null value for def is 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. + * + *

Returns the specified default if there is no value + * associated with the key, or if the backing store is inaccessible. + * A null value is treated as a non-existent value. + * + *

If the implementation supports stored defaults 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 key + * or the associated value cannot be interpreted as a String array, + * or the backing store is inaccessible. + * + * @return the String array value associated with + * key, or def if the + * associated value does not exist. + * + * @exception java.lang.IllegalArgumentException if key is null. (A + * null value for def is permitted.) + * + * @see #getValue(String,String) + */ + + public String[] getValues(String key, String[] def); + + + + /** + * Associates the specified String value with the specified key in this + * preference. + *

+ * The key cannot be null, but null values + * for the value parameter are allowed. + *

+ * If the same key contained already a String or String[] + * 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 null, + * or key.length() + * or value.length 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. + *

+ * The key cannot be null, but null values + * in the values parameter are allowed. + *

+ * If the same key contained already a String or String[] + * 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 null, or + * key.length() + * is to long or value.size 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 Enumeration if no keys are + * available. + * + * @return an Enumeration of the keys that have an associated value, + * or an empty Enumeration if no keys are + * available. + */ + public java.util.Enumeration getNames(); + + /** + * Returns a Map of the preferences. + *

+ * The values in the returned Map are from type + * String array (String[]). + *

+ * If no preferences exist this method returns an empty Map. + * + * @return an immutable Map containing preference names as + * keys and preference values as map values, or an empty Map + * 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 (String[]). + */ + + public java.util.Map getMap(); + + + /** + * Resets or removes the value associated with the specified key. + *

+ * 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. + *

+ * If there is no default available the key will be removed. + * + * @param key to reset + * + * @exception java.lang.IllegalArgumentException if key is null. + * @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 + * set methods in the persistent store. + *

+ * 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. + *

+ * All changes made to preferences not followed by a call + * to the store method are discarded when the + * portlet finishes the processAction method. + *

+ * 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 + * ValidatorException 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; + + +} http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/4fc38552/portlet-api/src/main/java/javax/portlet/PortletRequest.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletRequest.java b/portlet-api/src/main/java/javax/portlet/PortletRequest.java new file mode 100644 index 0000000..e42dc4d --- /dev/null +++ b/portlet-api/src/main/java/javax/portlet/PortletRequest.java @@ -0,0 +1,944 @@ +/* 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 PortletRequest defines the base interface to provide client + * request information to a portlet. The portlet container uses two specialized + * versions of this interface when invoking a portlet, ActionRequest + * and RenderRequest. The portlet container creates these objects and + * passes them as arguments to the portlet's processAction and + * render methods. + * + * @see ActionRequest + * @see RenderRequest + */ +public interface PortletRequest +{ + + /** Used to retrieve user information attributes with the + * getAttribute call. The user information is returned + * as a Map object. The portlet must define the + * user information attribute it is interested in inside the + * user-attribute section of the deployment descriptor. + * If an attribute is not supported + * by the current runtime system it will not show up in the user + * attribute map.
+ * If the user-attribute is supported by the runtime system, but not + * defined for a particular user, then for that user the attribute + * exists in the returned map and the attribute has a null value. + *

+ * If the user-attribute is not defined for the current user it + * will not show up in the Map. + *

+ * The value is javax.portlet.userinfo. + */ + public static final String USER_INFO = "javax.portlet.userinfo"; + + /** + * Used to retrieve an instance of the javax.ccpp.Profile + * with the getAttribute call. The returned profile is based + * on the current portlet request and may contain additional CC/PP + * information set by the portal / portlet container. + *

+ * The value is javax.portlet.ccpp. + * + * @since 2.0 + */ + public static final String CCPP_PROFILE = "javax.portlet.ccpp"; + + /** + * String identifier for Basic authentication. Value "BASIC". + */ + public static final String BASIC_AUTH = "BASIC"; + + /** + * String identifier for Form based authentication. Value "FORM". + */ + public static final String FORM_AUTH = "FORM"; + + /** + * String identifier for Certification based authentication. Value "CLIENT_CERT". + */ + public static final String CLIENT_CERT_AUTH = "CLIENT_CERT"; + + /** + * String identifier for Digest based authentication. Value "DIGEST". + */ + public static final String DIGEST_AUTH = "DIGEST"; + + /** + * P3P user information constants. + *

+ * Note: these are only available in the Java SE 5.0 supported version + * of the API. + * + * @since 2.0 + */ + public enum P3PUserInfos { + USER_BDATE_YMD_YEAR("user.bdate.ymd.year"), USER_BDATE_YMD_MONTH("user.bdate.ymd.month"), + USER_BDATE_YMD_DAY("user.bdate.ymd.day"), USER_BDATE_HMS_HOUR("user.bdate.hms.hour"), + USER_BDATE_HMS_MINUTE("user.bdate.hms.minute"), USER_BDATE_HMS_SECOND("user.bdate.hms.second"), + USER_BDATE_FRACTIONSECOND("user.bdate.fractionsecond"), USER_BDATE_TIMEZONE("user.bdate.timezone"), + USER_GENDER("user.gender"), USER_EMPLOYER("user.employer"), + USER_DEPARTMENT("user.department"), USER_JOBTITLE("user.jobtitle"), + USER_NAME_PREFIX("user.name.prefix"), USER_NAME_GIVEN("user.name.given"), + USER_NAME_FAMILY("user.name.family"), USER_NAME_MIDDLE("user.name.middle"), + USER_NAME_SUFFIX("user.name.suffix"), USER_NAME_NICKNAME("user.name.nickName"), + USER_LOGIN_ID("user.login.id"), + USER_HOMEINFO_POSTAL_NAME("user.home-info.postal.name"), + USER_HOMEINFO_POSTAL_STREET("user.home-info.postal.street"), + USER_HOMEINFO_POSTAL_CITY("user.home-info.postal.city"), + USER_HOMEINFO_POSTAL_STATEPROV("user.home-info.postal.stateprov"), + USER_HOMEINFO_POSTAL_POSTALCODE("user.home-info.postal.postalcode"), + USER_HOMEINFO_POSTAL_COUNTRY("user.home-info.postal.country"), + USER_HOMEINFO_POSTAL_ORGANIZATION("user.home-info.postal.organization"), + USER_HOMEINFO_TELECOM_TELEPHONE_INTCODE("user.home-info.telecom.telephone.intcode"), + USER_HOMEINFO_TELECOM_TELEPHONE_LOCCODE("user.home-info.telecom.telephone.loccode"), + USER_HOMEINFO_TELECOM_TELEPHONE_NUMBER("user.home-info.telecom.telephone.number"), + USER_HOMEINFO_TELECOM_TELEPHONE_EXT("user.home-info.telecom.telephone.ext"), + USER_HOMEINFO_TELECOM_TELEPHONE_COMMENT("user.home-info.telecom.telephone.comment"), + USER_HOMEINFO_TELECOM_FAX_INTCODE("user.home-info.telecom.fax.intcode"), + USER_HOMEINFO_TELECOM_FAX_LOCCODE("user.home-info.telecom.fax.loccode"), + USER_HOMEINFO_TELECOM_FAX_NUMBER("user.home-info.telecom.fax.number"), + USER_HOMEINFO_TELECOM_FAX_EXT("user.home-info.telecom.fax.ext"), + USER_HOMEINFO_TELECOM_FAX_COMMENT("user.home-info.telecom.fax.comment"), + USER_HOMEINFO_TELECOM_MOBILE_INTCODE("user.home-info.telecom.mobile.intcode"), + USER_HOMEINFO_TELECOM_MOBILE_LOCCODE("user.home-info.telecom.mobile.loccode"), + USER_HOMEINFO_TELECOM_MOBILE_NUMBER("user.home-info.telecom.mobile.number"), + USER_HOMEINFO_TELECOM_MOBILE_EXT("user.home-info.telecom.mobile.ext"), + USER_HOMEINFO_TELECOM_MOBILE_COMMENT("user.home-info.telecom.mobile.comment"), + USER_HOMEINFO_TELECOM_PAGER_INTCODE("user.home-info.telecom.pager.intcode"), + USER_HOMEINFO_TELECOM_PAGER_LOCCODE("user.home-info.telecom.pager.loccode"), + USER_HOMEINFO_TELECOM_PAGER_NUMBER("user.home-info.telecom.pager.number"), + USER_HOMEINFO_TELECOM_PAGER_EXT("user.home-info.telecom.pager.ext"), + USER_HOMEINFO_TELECOM_PAGER_COMMENT("user.home-info.telecom.pager.comment"), + USER_HOMEINFO_ONLINE_EMAIL("user.home-info.online.email"), + USER_HOMEINFO_ONLINE_URI("user.home-info.online.uri"), + USER_BUSINESSINFO_POSTAL_NAME("user.business-info.postal.name"), + USER_BUSINESSINFO_POSTAL_STREET("user.business-info.postal.street"), + USER_BUSINESSINFO_POSTAL_CITY("user.business-info.postal.city"), + USER_BUSINESSINFO_POSTAL_STATEPROV("user.business-info.postal.stateprov"), + USER_BUSINESSINFO_POSTAL_POSTALCODE("user.business-info.postal.postalcode"), + USER_BUSINESSINFO_POSTAL_COUNTRY("user.business-info.postal.country"), + USER_BUSINESSINFO_POSTAL_ORGANIZATION("user.business-info.postal.organization"), + USER_BUSINESSINFO_TELECOM_TELEPHONE_INTCODE("user.business-info.telecom.telephone.intcode"), + USER_BUSINESSINFO_TELECOM_TELEPHONE_LOCCODE("user.business-info.telecom.telephone.loccode"), + USER_BUSINESSINFO_TELECOM_TELEPHONE_NUMBER("user.business-info.telecom.telephone.number"), + USER_BUSINESSINFO_TELECOM_TELEPHONE_EXT("user.business-info.telecom.telephone.ext"), + USER_BUSINESSINFO_TELECOM_TELEPHONE_COMMENT("user.business-info.telecom.telephone.comment"), + USER_BUSINESSINFO_TELECOM_FAX_INTCODE("user.business-info.telecom.fax.intcode"), + USER_BUSINESSINFO_TELECOM_FAX_LOCCODE("user.business-info.telecom.fax.loccode"), + USER_BUSINESSINFO_TELECOM_FAX_NUMBER("user.business-info.telecom.fax.number"), + USER_BUSINESSINFO_TELECOM_FAX_EXT("user.business-info.telecom.fax.ext"), + USER_BUSINESSINFO_TELECOM_FAX_COMMENT("user.business-info.telecom.fax.comment"), + USER_BUSINESSINFO_TELECOM_MOBILE_INTCODE("user.business-info.telecom.mobile.intcode"), + USER_BUSINESSINFO_TELECOM_MOBILE_LOCCODE("user.business-info.telecom.mobile.loccode"), + USER_BUSINESSINFO_TELECOM_MOBILE_NUMBER("user.business-info.telecom.mobile.number"), + USER_BUSINESSINFO_TELECOM_MOBILE_EXT("user.business-info.telecom.mobile.ext"), + USER_BUSINESSINFO_TELECOM_MOBILE_COMMENT("user.business-info.telecom.mobile.comment"), + USER_BUSINESSINFO_TELECOM_PAGER_INTCODE("user.business-info.telecom.pager.intcode"), + USER_BUSINESSINFO_TELECOM_PAGER_LOCCODE("user.business-info.telecom.pager.loccode"), + USER_BUSINESSINFO_TELECOM_PAGER_NUMBER("user.business-info.telecom.pager.number"), + USER_BUSINESSINFO_TELECOM_PAGER_EXT("user.business-info.telecom.pager.ext"), + USER_BUSINESSINFO_TELECOM_PAGER_COMMENT("user.business-info.telecom.pager.comment"), + USER_BUSINESSINFO_ONLINE_EMAIL("user.business-info.online.email"), + USER_BUSINESSINFO_ONLINE_URI("user.business-info.online.uri"); + P3PUserInfos(String value) {this.value = value; } + private final String value; + public String toString() {return value;} + } + + /** + * String identifier for the portlet action lifecycle phase. In this + * phase the portlet request and response are from type + * ActionRequest and ActionResponse. + *

+ * The value of the constant is ACTION_PHASE. + * + * @since 2.0 + */ + public static final String ACTION_PHASE = "ACTION_PHASE"; + + /** + * String identifier for the portlet event lifecycle phase. In this + * phase the portlet request and response are from type + * EventRequest and EventResponse. + *

+ * The value of the constant is EVENT_PHASE. + * + * @since 2.0 + */ + public static final String EVENT_PHASE = "EVENT_PHASE"; + + /** + * String identifier for the portlet render lifecycle phase. In this + * phase the portlet request and response are from type + * RenderRequest and RenderResponse. + *

+ * The value of the constant is RENDER_PHASE. + * + * @since 2.0 + */ + public static final String RENDER_PHASE = "RENDER_PHASE"; + + /** + * String identifier for the portlet resource serving lifecycle phase. In this + * phase the portlet request and response are from type + * ResourceRequest and ResourceResponse. + *

+ * The value of the constant is RESOURCE_PHASE. + * + * @since 2.0 + */ + public static final String RESOURCE_PHASE = "RESOURCE_PHASE"; + + /** + * Provides the portlet lifecycle phase of the current request + * as request attribute. + *

+ * Valid values are: ACTION_PHASE, EVENT_PHASE, RENDER_PHASE, + * RESOURCE_SERVING_PHASE. + *

+ * The value of the constant is javax.portlet.lifecylce_phase. + * + * @since 2.0 + */ + public static final String LIFECYCLE_PHASE = "javax.portlet.lifecycle_phase"; + + + /** + * The RENDER_PART portlet request attribute is set by portals + * that are streaming based and therefore need to split the + * render phase into two parts: first the RENDER_HEADERS part + * where the portlet should only set the header related data + * and the portlet title, and second the RENDER_MARKUP part + * in which the portlet should produce its markup. + *

+ * Non-streaming portals will not set this attribute and thus + * the portlet should set headers, portlet title and produce + * its markup in a single render request. + *

+ * The value of the constant is javax.portlet.render_part. + * + * @since 2.0 + */ + public static final String RENDER_PART = "javax.portlet.render_part"; + + /** + * The RENDER_HEADERS is a possible value of the RENDER_PART + * request attribute and denotes that the portlet should set + * the intended headers and the portlet title of this render + * request. + *

+ * The value of the constant is RENDER_HEADERS. + * + * @since 2.0 + */ + public static final String RENDER_HEADERS = "RENDER_HEADERS"; + + /** + * The RENDER_MARKUP is a possible value of the RENDER_PART + * request attribute and denotes that the portlet should + * produce its markup for this render request. + *

+ * The value of the constant is RENDER_MARKUP. + * + * @since 2.0 + */ + public static final String RENDER_MARKUP = "RENDER_MARKUP"; + + /** + * The action scope ID that the portlet container uses + * for storing the current action scope as render parameter + * if the javax.portlet.actionScopedRequestAttributes + * container runtime option is used by the portlet. + *

+ * The value is javax.portlet.as. + * @since 2.0 + */ + public static final String ACTION_SCOPE_ID = "javax.portlet.as"; + + + /** + * Returns true, if the given window state is valid + * to be set for this portlet in the context + * of the current request. + * + * @param state window state to checked + * + * @return true, if it is valid for this portlet + * in this request to change to the + * given window state + * + */ + public boolean isWindowStateAllowed(WindowState state); + + +/** + * Returns true, if the given portlet mode is a valid + * one to set for this portlet in the context + * of the current request. + * + * @param mode portlet mode to check + * + * @return true, if it is valid for this portlet + * in this request to change to the + * given portlet mode + * + */ + + public boolean isPortletModeAllowed(PortletMode mode); + + + /** + * Returns the current portlet mode of the portlet. + * + * @return the portlet mode + */ + + public PortletMode getPortletMode (); + + + /** + * Returns the current window state of the portlet. + * + * @return the window state + */ + + public WindowState getWindowState (); + + + /** + * Returns the preferences object associated with the portlet. + * + * @return the portlet preferences + */ + public PortletPreferences getPreferences (); + + + /** + * Returns the current portlet session or, if there is no current session, + * creates one and returns the new session. + *

+ * Creating a new portlet session will result in creating + * a new HttpSession on which the portlet session is based on. + * + * @return the portlet session + */ + + public PortletSession getPortletSession (); + + + /** + * Returns the current portlet session or, if there is no current session + * and the given flag is true, creates one and returns + * the new session. + *

+ * If the given flag is false and there is no current + * portlet session, this method returns null. + *

+ * Creating a new portlet session will result in creating + * a new HttpSession on which the portlet session is based on. + * + * @param create + * true to create a new session,
+ * false to return null if there + * is no current session + * @return the portlet session + * + */ + + public PortletSession getPortletSession (boolean create); + + + /** + * Returns the value of the specified request property + * as a String. If the request did not include a property + * of the specified name, this method returns null. + *

+ * A portlet can access portal/portlet-container specific properties + * through this method and, if available, the + * headers of the HTTP client request. + *

+ * This method should only be used if the + * property has only one value. If the property might have + * more than one value, use {@link #getProperties}. + *

+ * If this method is used with a multivalued + * parameter, the value returned is equal to the first value + * in the Enumeration returned by getProperties. + * + * @param name a String specifying the + * property name + * + * @return a String containing the + * value of the requested + * property, or null + * if the request does not + * have a property of that name. + * + * @exception java.lang.IllegalArgumentException + * if name is null. + */ + + public String getProperty(String name); + + + /** + * Returns all the values of the specified request property + * as a Enumeration of String objects. + *

+ * If the request did not include any properties + * of the specified name, this method returns an empty + * Enumeration. + * The property name is case insensitive. You can use + * this method with any request property. + * + * @param name a String specifying the + * property name + * + * @return a Enumeration containing + * the values of the requested property. If + * the request does not have any properties of + * that name return an empty Enumeration. + * + * @exception java.lang.IllegalArgumentException + * if name is null. + */ + + public java.util.Enumeration getProperties(String name); + + + /** + * + * Returns a Enumeration of all the property names + * this request contains. If the request has no + * properties, this method returns an empty Enumeration. + * + * + * @return an Enumeration of all the + * property names sent with this + * request; if the request has + * no properties, an empty Enumeration. + */ + + public java.util.Enumeration getPropertyNames(); + + + /** + * Returns the context of the calling portal. + * + * @return the context of the calling portal + */ + + public PortalContext getPortalContext(); + + + /** + * Returns the name of the authentication scheme used for the + * connection between client and portal, + * for example, BASIC_AUTH, CLIENT_CERT_AUTH, + * a custom one or null if there was no authentication. + * + * @return one of the static members BASIC_AUTH, + * FORM_AUTH, CLIENT_CERT_AUTH, + * DIGEST_AUTH (suitable for == comparison) + * indicating the authentication scheme, + * a custom one, or + * null if the request was + * not authenticated. + */ + + public java.lang.String getAuthType(); + + + /** + * Returns the context path which is the path prefix associated with the deployed + * portlet application. If the portlet application is rooted at the + * base of the web server URL namespace (also known as "default" context), + * this path must be an empty string. Otherwise, it must be the path the + * portlet application is rooted to, the path must start with a '/' and + * it must not end with a '/' character. + *

+ * To encode a URL the {@link PortletResponse#encodeURL} method must be used. + * + * @return a String specifying the + * portion of the request URL that indicates the context + * of the request + * + * @see PortletResponse#encodeURL + */ + + public String getContextPath(); + + + /** + * Returns the login of the user making this request, if the user + * has been authenticated, or null if the user has not been authenticated. + * + * @return a String specifying the login + * of the user making this request, or null + * if the user login is not known. + * + */ + + public java.lang.String getRemoteUser(); + + + /** + * Returns a java.security.Principal object containing the name of the + * current authenticated user. + * + * @return a java.security.Principal containing + * the name of the user making this request, or + * null if the user has not been + * authenticated. + */ + + public java.security.Principal getUserPrincipal(); + + + /** + * Returns a boolean indicating whether the authenticated user is + * included in the specified logical "role". Roles and role membership can be + * defined using deployment descriptors. If the user has not been + * authenticated, the method returns false. + * + * @param role a String specifying the name + * of the role + * + * @return a boolean indicating whether + * the user making this request belongs to a given role; + * false if the user has not been + * authenticated. + */ + + public boolean isUserInRole(java.lang.String role); + + + /** + * + * Returns the value of the named attribute as an Object, + * or null if no attribute of the given name exists. + *

+ * Attribute names should follow the same conventions as package + * names. This specification reserves names matching java.*, + * and javax.*. + *

+ * In a distributed portlet web application the Object + * needs to be serializable. + * + * @param name a String specifying the name of + * the attribute + * + * @return an Object containing the value + * of the attribute, or null if + * the attribute does not exist. + * + * @exception java.lang.IllegalArgumentException + * if name is null. + * + */ + + public Object getAttribute(String name); + + + /** + * Returns an Enumeration containing the + * names of the attributes available to this request. + * This method returns an empty Enumeration + * if the request has no attributes available to it. + * + * + * @return an Enumeration of strings + * containing the names + * of the request attributes, or an empty + * Enumeration if the request + * has no attributes available to it. + */ + + public java.util.Enumeration getAttributeNames(); + + + /** + * Returns the value of a request parameter as a String, + * or null if the parameter does not exist. Request parameters + * are extra information sent with the request. The returned parameter + * are "x-www-form-urlencoded" decoded. + *

+ * 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 #getParameterValues}. + *

+ * If this method is used with a multivalued + * parameter, the value returned is equal to the first value + * in the array returned by getParameterValues. + * + * + * + * @param name a String specifying the + * name of the parameter + * + * @return a String representing the + * single value of the parameter + * + * @see #getParameterValues + * + * @exception java.lang.IllegalArgumentException + * if name is null. + * + */ + + public String getParameter(String name); + + + /** + * + * Returns an Enumeration of String + * objects containing the names of the parameters contained + * in this request. If the request has + * no parameters, the method returns an + * empty Enumeration. + *

+ * Only parameters targeted to the current portlet are returned. + * + * + * @return an Enumeration of String + * objects, each String containing + * the name of a request parameter; or an + * empty Enumeration if the + * request has no parameters. + */ + + public java.util.Enumeration getParameterNames(); + + + /** + * Returns an array of String objects containing + * all of the values the given request parameter has, or + * null if the parameter does not exist. + * The returned parameters are "x-www-form-urlencoded" decoded. + *

+ * If the parameter has a single value, the array has a length + * of 1. + * + * + * @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. + * + * @see #getParameter + * + * @exception java.lang.IllegalArgumentException + * if name is null. + * + */ + + public String[] getParameterValues(String name); + + + /** + * Returns a Map of the parameters of this request. + * Request parameters are extra information sent with the request. + * The returned parameters are "x-www-form-urlencoded" decoded. + *

+ * The values in the returned Map are from type + * String array (String[]). + *

+ * If no parameters exist this method returns an empty Map. + * + * @return an immutable 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[]). + */ + + public java.util.Map getParameterMap(); + + + /** + * Returns a boolean indicating whether this request was made + * using a secure channel between client and the portal, such as HTTPS. + * + * @return true, if the request was made using a secure channel. + */ + + public boolean isSecure(); + + + /** + * Stores an attribute in this request. + * + *

Attribute names should follow the same conventions as + * package names. Names beginning with java.*, + * javax.*, and com.sun.* are + * reserved. + *
If the value passed into this method is null, + * the effect is the same as calling {@link #removeAttribute}. + * + * + * @param name a String specifying + * the name of the attribute + * + * @param o the Object to be stored + * + * + * @exception java.lang.IllegalArgumentException + * if name is null. + */ + + public void setAttribute(String name, Object o); + + + /** + * + * Removes an attribute from this request. This method is not + * generally needed, as attributes only persist as long as the request + * is being handled. + * + *

Attribute names should follow the same conventions as + * package names. Names beginning with java.*, + * javax.*, and com.sun.* are + * reserved. + * + * @param name a String specifying + * the name of the attribute to be removed + * + * + * @exception java.lang.IllegalArgumentException + * if name is null. + */ + + public void removeAttribute(String name); + + + /** + * + * Returns the session ID indicated in the client request. + * This session ID may not be a valid one, it may be an old + * one that has expired or has been invalidated. + * If the client request + * did not specify a session ID, this method returns + * null. + * + * @return a String specifying the session + * ID, or null if the request did + * not specify a session ID + * + * @see #isRequestedSessionIdValid + * + */ + + public String getRequestedSessionId(); + + + /** + * + * Checks whether the requested session ID is still valid. + * + * @return true if this + * request has an id for a valid session + * in the current session context; + * false otherwise + * + * @see #getRequestedSessionId + * @see #getPortletSession + */ + + public boolean isRequestedSessionIdValid(); + + + /** + * Returns the portal preferred content type for the response. + *

+ * The following restrictions apply: + *

    + *
  • The content type only includes the MIME type, not the + * character set. The character set of the response + * can be retrieved via the {@link RenderResponse#getCharacterEncoding}.
    • + *
  • Only content types that the portlet has defined in its + * deployment descriptor are valid return values for + * this method call. If the portlet has defined + * '*' or '* / *' as supported content + * types, these may also be valid return values.
    • + *
+ * + * @return preferred MIME type of the response + */ + + public String getResponseContentType(); + + + /** + * Gets a list of content types which the portal accepts for the response. + * This list is ordered with the most preferable types listed first. + *

+ * The following restrictions apply: + *

    + *
  • The content type only includes the MIME type, not the + * character set.
    • + *
  • Only content types that the portlet has defined in its + * deployment descriptor are valid return values for + * this method call. If the portlet has defined + * '*' or '* / *' as supported content + * types, these may also be valid return values.
    • + *
+ * + * @return ordered list of MIME types for the response + */ + + public java.util.Enumeration getResponseContentTypes(); + + + /** + * Returns the preferred Locale in which the portal will accept content. + * The Locale may be based on the Accept-Language header of the client. + * + * @return the preferred Locale in which the portal will accept content. + */ + + public java.util.Locale getLocale(); + + + /** + * Returns an Enumeration of Locale objects indicating, in decreasing + * order starting with the preferred locale in which the portal will + * accept content for this request. + * The Locales may be based on the Accept-Language header of the client. + * + * @return an Enumeration of Locales, in decreasing order, in which + * the portal will accept content for this request + */ + + public java.util.Enumeration getLocales(); + + + /** + * Returns the name of the scheme used to make this request. + * For example, http, https, or ftp. + * Different schemes have different rules for constructing URLs, + * as noted in RFC 1738. + * + * @return a String containing the name + * of the scheme used to make this request + */ + + public String getScheme(); + + + /** + * Returns the host name of the server that received the request. + * + * @return a String containing the name + * of the server to which the request was sent + */ + + public String getServerName(); + + + /** + * Returns the port number on which this request was received. + * + * @return an integer specifying the port number + */ + + public int getServerPort(); + + /** + * Returns the portlet window ID. The portlet window ID is + * unique for this portlet window and is constant for the lifetime + * of the portlet window. + *

+ * This ID is the same that is used by the portlet container for + * scoping the portlet-scope session attributes. + * + * @since 2.0 + * @return the portlet window ID + */ + public String getWindowID(); + + + /** + * Returns an array containing all of the Cookie properties. + *

+ * This method returns null if no cookies exist. + * + * @since 2.0 + * @return array of cookie properties, or + * null if no cookies exist. + * @see MimeResponse#addProperty(Cookie) + */ + public javax.servlet.http.Cookie[] getCookies(); + + /** + * Returns a Map of the private parameters of this request. + * Private parameters are not shared with other portlets or components. + * The returned parameters are "x-www-form-urlencoded" decoded. + *

+ * The values in the returned Map are from type + * String array (String[]). + *

+ * If no private parameters exist this method returns an empty Map. + * + * @since 2.0 + * @return an immutable Map containing private parameter names as + * keys and private parameter values as map values, or an empty Map + * if no private parameters exist. The keys in the parameter + * map are of type String. The values in the parameter map are of type + * String array (String[]). + */ + public java.util.Map getPrivateParameterMap(); + + /** + * Returns a Map of the public parameters of this request. + * Public parameters may be shared with other portlets or components and + * defined in the portlet deployment descriptor with the + * supported-public-render-parameter element. + * The returned parameters are "x-www-form-urlencoded" decoded. + *

+ * The values in the returned Map are from type + * String array (String[]). + *

+ * If no public parameters exist this method returns an empty Map. + * + * @since 2.0 + * @return an immutable Map containing public parameter names as + * keys and public parameter values as map values, or an empty Map + * if no public parameters exist. The keys in the parameter + * map are of type String. The values in the parameter map are of type + * String array (String[]). + */ + public java.util.Map getPublicParameterMap(); + +} http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/4fc38552/portlet-api/src/main/java/javax/portlet/PortletRequestDispatcher.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletRequestDispatcher.java b/portlet-api/src/main/java/javax/portlet/PortletRequestDispatcher.java new file mode 100644 index 0000000..8205872 --- /dev/null +++ b/portlet-api/src/main/java/javax/portlet/PortletRequestDispatcher.java @@ -0,0 +1,142 @@ +/* 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 PortletRequestDispatcher interface defines an object that + * receives requests from the client and sends them to the specified resources + * (such as a servlet, HTML file, or JSP file) on the server. The portlet + * container creates the PortletRequestDispatcher object, which + * is used as a wrapper around a server resource located at a particular path or + * given by a particular name. + * + */ + +public interface PortletRequestDispatcher { + + /** + * + * Includes the content of a resource (servlet, JSP page, HTML file) in the + * response. In essence, this method enables programmatic server-side + * includes. + *

+ * The included servlet cannot set or change the response status code or set + * headers; any attempt to make a change is ignored. + *

+ * This method is kept in order to provide backward compatibility with + * version 1.0. Please use {@link #include(PortletRequest, PortletResponse)} instead + * of this method. + * + * @param request + * a {@link RenderRequest} object that contains the client + * request. Must be either the render request passed to the + * portlet in render or a wrapped version of this + * render request. + * + * @param response + * a {@link RenderResponse} object that contains the render + * response. Must be either the render response passed to the + * portlet in render or a wrapped version of this + * render response. + * + * @exception PortletException + * if the included resource throws a ServletException, or + * other exceptions that are not Runtime- or IOExceptions. + * + * @exception java.io.IOException + * if the included resource throws this exception + * + * + */ + + public void include(RenderRequest request, RenderResponse response) + throws PortletException, java.io.IOException; + + /** + * + * Includes the content of a resource (servlet, JSP page, HTML file) in the + * response. In essence, this method enables programmatic server-side + * includes. + *

+ * The included servlet cannot set or change the response status code or set + * headers; any attempt to make a change is ignored. + * + * + * @param request + * a {@link PortletRequest} object that contains the portlet + * request. Must be either the original request passed to the + * portlet or a wrapped version of this request. + * + * @param response + * a {@link PortletResponse} object that contains the portlet + * response. Must be either the portlet response passed to the + * portlet or a wrapped version of this response. + * + * @exception PortletException + * if the included resource throws a ServletException, or + * other exceptions that are not Runtime- or IOExceptions. + * + * @exception java.io.IOException + * if the included resource throws this exception + * + * @since 2.0 + */ + + public void include(PortletRequest request, PortletResponse response) + throws PortletException, java.io.IOException; + + /** + * Forwards a portlet request from a portlet to another resource (servlet, JSP file, or HTML file) + * on the server. This method allows the portlet to do preliminary processing of a + * request and another resource to generate the response. + *

+ * The forward method should be called before the response has been + * committed to the portlet container (before response body output has been flushed). + * If the response already has been committed, this method throws an + * IllegalStateException. Uncommitted output in the response buffer + * is automatically cleared before the forward. + *

+ * The request and response parameters must be either the same objects as were passed to + * the calling portlet or be wrapped versions of these. + * + * @param request a request object that represents the request to the + * portlet + * @param response a reponse object that contains the portlet response + * + * @exception PortletException + * if the included resource throws a ServletException, or + * other exceptions that are not Runtime- or IOExceptions. + * @exception java.io.IOException + * if the included resource throws this exception + * @exception java.lang.IllegalStateException + * if the response was already committed + * @since 2.0 + */ + public void forward(PortletRequest request, PortletResponse response) + throws PortletException, java.io.IOException; + + + +} http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/4fc38552/portlet-api/src/main/java/javax/portlet/PortletResponse.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletResponse.java b/portlet-api/src/main/java/javax/portlet/PortletResponse.java new file mode 100644 index 0000000..6dccbf0 --- /dev/null +++ b/portlet-api/src/main/java/javax/portlet/PortletResponse.java @@ -0,0 +1,196 @@ +/* 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 PortletResponse defines the base interface to assist a + * portlet in creating and sending a response to the client. The portlet + * container uses specialized versions of this interface when invoking a + * portlet. + * The portlet container creates these objects and passes them as arguments to + * the portlet's processAction, processEvent, serveResource and render methods. + * + * @see ActionResponse + * @see RenderResponse + * @see EventResponse + * @see ResourceResponse + */ +public interface PortletResponse { + + + /** + * Adds a String property to an existing key to be returned to the portal. + * If there are no property values already associated with the key, + * a new key is created. + *

+ * This method allows response properties to have multiple values. + *

+ * Response properties can be viewed as header values set for the portal application. + * If these header values are intended to be transmitted to the client they should be + * set before the response is committed. + * + * @param key + * the key of the property to be returned to the portal + * @param value + * the value of the property to be returned to the portal + * + * @exception java.lang.IllegalArgumentException + * if key is null. + */ + + public void addProperty(String key, String value); + + + /** + * Sets a String property to be returned to the portal. + *

+ * Response properties can be viewed as header values set for the portal application. + * If these header values are intended to be transmitted to the client they should be + * set before the response is committed. + *

+ * This method resets all properties previously added with the same key. + * + * @param key + * the key of the property to be returned to the portal + * @param value + * the value of the property to be returned to the portal + * + * @exception java.lang.IllegalArgumentException + * if key is null. + */ + + public void setProperty(String key, String value); + + /** + * Returns the encoded URL of the resource, like servlets, JSPs, images and + * other static files, at the given path. + *

+ * Portlets should encode all resource URLs pointing to resources in the + * portlet application via this method in order to ensure that they get + * served via the portal application. + *

+ * Some portal/portlet-container implementation may require those URLs to + * contain implementation specific data encoded in it. Because of that, + * portlets should use this method to create such URLs. + *

+ * The encodeURL method may include the session ID and other + * portal/portlet-container specific information into the URL. If encoding + * is not needed, it returns the URL unchanged. + *

+ * Portlet developer should be aware that the returned URL might not be a well formed + * URL but a special token at the time the portlet is generating its content. + * Thus portlets should not add additional parameters on the resulting URL or + * expect to be able to parse the URL. As a result, the outcome of the encodeURL + * call may be different than calling encodeURL in the servlet world. + * + * @param path + * the URI path to the resource. This must be either an absolute + * URL (e.g. + * http://my.co/myportal/mywebap/myfolder/myresource.gif) + * or a full path URI (e.g. + * /myportal/mywebap/myfolder/myresource.gif). + * + * @exception java.lang.IllegalArgumentException + * if path doesn't have a leading slash or is not an absolute + * URL + * + * @return the encoded resource URL as string, may not be a valid URL + */ + + public String encodeURL(String path); + + /** + * The value returned by this method should be prefixed or appended to + * elements, such as JavaScript variables or function names, to ensure they + * are unique in the context of the portal page. + *

+ * The namespace value must be constant for the lifetime of the portlet + * window. + * + * @return the namespace + */ + + public String getNamespace(); + + /** + * Adds a HTTP Cookie property to the response.
+ * The portlet should note that the cookie may not make + * it to the client, but may be stored at the portal. + *

+ * This method allows response properties to have multiple cookies. + *

+ * + * @param cookie the cookie to be added to the response + * + * @exception java.lang.IllegalArgumentException + * if cookie is null. + * @since 2.0 + */ + + public void addProperty(javax.servlet.http.Cookie cookie); + + + /** + * Adds an XML DOM element property to the response. + *

+ * If a DOM element with the provided key already exists + * the provided element will be stored in addition to the + * existing element under the same key. + *

+ * If the element is null the key is removed from + * the response. + *

+ * Response XML DOM element properties can be viewed as + * additional response document sections + * set for the portal application. + * If these header values are intended to be transmitted to the client they should be + * set before the response is committed. + * + * @param key + * the key of the property to be returned to the portal + * @param element + * the XML DOM element to be added to the response + * + * @exception java.lang.IllegalArgumentException + * if key is null. + * @since 2.0 + */ + void addProperty(String key, org.w3c.dom.Element element); + + /** + * Creates an element of the type specified to be used in the + * {@link #addProperty(String,Element)} method. + * + * @param tagName name of the element type to instantiate + * @return A new Element object with the nodeName attribute set to tagName, + * and localName, prefix, and namespaceURI set to null. + * @throws org.w3c.dom.DOMException + * INVALID_CHARACTER_ERR: Raised if the specified name + * contains an illegal character. + */ + org.w3c.dom.Element createElement(String tagName) throws org.w3c.dom.DOMException; + + +} http://git-wip-us.apache.org/repos/asf/portals-pluto/blob/4fc38552/portlet-api/src/main/java/javax/portlet/PortletSecurityException.java ---------------------------------------------------------------------- diff --git a/portlet-api/src/main/java/javax/portlet/PortletSecurityException.java b/portlet-api/src/main/java/javax/portlet/PortletSecurityException.java new file mode 100644 index 0000000..75104c9 --- /dev/null +++ b/portlet-api/src/main/java/javax/portlet/PortletSecurityException.java @@ -0,0 +1,91 @@ +/* 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; + +/** + * A portlet should throw a PortletSecurityException + * when a call fails because of security reasons.
+ * Additionally it can be thrown by the portal/portlet-container. + */ + +public class PortletSecurityException extends PortletException +{ + + private static final long serialVersionUID = 1L; + + private PortletSecurityException () + { + } + + /** + * Constructs a new security exception with the given text. The + * portlet container may use the text write it to a log. + * + * @param text + * the exception text + */ + + public PortletSecurityException (String text) + { + super (text); + } + + /** + * Constructs a new portlet security exception when the portlet needs to do + * the following: + *

    + * throw an exception + *
  • include a message about the "root cause" that interfered + * with its normal operation + *
  • include a description message + *
+ * + * @param text + * the exception text + * @param cause + * the root cause + */ + + public PortletSecurityException (String text, Throwable cause) + { + super(text, cause); + } + + /** + * Constructs a new portlet security exception when the portlet needs to throw an + * exception. The exception message is based on the localized message + * of the underlying exception. + * + * @param cause + * the root cause + */ + + public PortletSecurityException (Throwable cause) + { + super(cause); + } + + +}