PORTIONS (PORTlet actIONS)PORTIONS (PORTlet actIONS)[español|english]
- Abrir nueva ventana - Enlace externo
A continuación puedes consultar la Guía de Usuario, aunque si lo prefieres puedes descargarte la Guía de Usuario del framework PORTIONS en formato PDF (103KB aproximadamente).
portlet.xml
<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
<portlet>
<description>
Descripción del portlet de ejemplo
</description>
<portlet-name>
PortletDeEjemplo
</portlet-name>
<display-name>
Portlet de Ejemplo
</display-name>
<portlet-class>
net.sf.portions.controller.PortletController
</portlet-class>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>VIEW</portlet-mode>
<portlet-mode>EDIT</portlet-mode>
<portlet-mode>HELP</portlet-mode>
</supports>
<supported-locale>en</supported-locale>
<portlet-info>
<title>Portlet de Ejemplo</title>
<short-title>PortletDeEjemplo</short-title>
<keywords>Palabras clave</keywords>
</portlet-info>
</portlet>
</portlet-app>
portlet-config.xml
<?xml version="1.0" encoding="UTF-8"?>
<portlet-config>
<form-beans>
<form-bean name="sampleForm"
type="net.sf.portions.sample.form.SamplePortletForm" />
...
</form-beans>
<global-forwards>
<forward name="success"
mode="view"
path="/jsp/view_1.jsp"
content="text/html"/>
<forward name="failure"
mode="view"
path="/jsp/view_1.jsp"
content="text/html"/>
...
</global-forwards>
<action-mappings>
<action name="step1"
type="net.sf.portions.sample.action.Step1PortletAction">
<forward name="success"
mode="view"
path="/jsp/view_1.jsp"
content="text/html"/>
</action>
<action name="step2"
type="net.sf.portions.sample.action.Step2PortletAction"
input="/jsp/view_1.jsp"
content="text/html"
formName="sampleForm">
<forward name="success"
mode="view"
path="/jsp/view_2.jsp"
content="text/html"/>
</action>
...
</action-mappings>
<message-resources parameter="resources.ApplicationResources" />
<plug-in className="net.sf.portions.validator.ValidatorPlugIn">
<set-property property="pathnames" value="/WEB-INF/validation.xml"/>
</plug-in>
</portlet-config>
Existen cinco secciones diferenciadas dentro del fichero de configuración portlet-config.xml:
elemento "form-beans": lista los diferentes formularios de la aplicación. Por cada formulario se definirá elemento "form-bean" con los siguientes atributos:
elemento "global-forwards": identifica las redirecciones (forwards) globales (por defecto) de la aplicación. Por cada redirección se definirá un elemento "forward" con los atributos:
elemento "action-mappings": mapea cada una de las actions de la aplicación utilizando elementos "action", que podrán tener los siguientes parámetros:
Además, cada elemento "action" contendrá tantos elementos "forward" (iguales que los definidos en la sección "global-forwards") como posibles redirecciones genere la ejecución de la action.
elemento "message-resources": especifica, a través del atributo "parameter", el archivo de properties con los recursos y mensajes propios de la aplicación.
lista de elementos "plug-in": permite listar los plug-ins (por ejemplo el plug-in de validación) que debe ejecutar el controlador. Por cada plug-in se especificará un elemento "plug-in", con el siguiente parámetro:
Si es necesario se podrán especificar propiedades de configuración para cada plug-in con los sub-elementos "set-property", que a su vez tienen los siguientes parámetros:
El controlador, dentro del patrón MVC, es el encargado del procesamiento de las peticiones de entrada y la creación de cualquier bean u objeto usado por las páginas JSP, así como de la toma de decisiones, dependiendo de las acciones del usuario, de a qué página JSP debe redireccionarse la salida. Estas tareas, dentro del framework PORTIONS, son llevadas a cabo por la clase PortletController.
La clase ConfigHelper permite obtener los datos de configuración de la aplicación indicados a través del fichero "portlet-config.xml".
Log de la clase
Realiza las tareas de inicialización del controlador, que incluyen el realizar una llamada al método init de la clase ConfigHelper para cargar los datos de configuración del fichero /WEB-INF/portlet-config.xml.
Renderiza el modo view del portlet.
Renderiza el modo edit del portlet.
Renderiza el modo help del portlet.
Procesa una petición de acción al portlet.
Permite obtener el forward actual al que el controlador ha de pasar el control.
Carga los datos de configuración a partir de la URL al fichero portlet-config.xml.
Retorna los datos de configuración de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad type de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad input de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad content de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad scope de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad formName de la action cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad parameter de la action cuyo nombre se pasa como parámetro.
Retorna un Map que contiene los forwards asociados a la action cuyo nombre se pasa como parámetro.
Retorna los datos de configuración del forward identificado a través de los parámetros pasados.
Retorna el valor de la propiedad path del forward identificado a través de los parámetros pasados.
Retorna el valor de la propiedad content del forward identificado a través de los parámetros pasados.
Retorna los datos de configuración del form cuyo nombre se pasa como parámetro.
Retorna el valor de la propiedad type del form cuyo nombre se pasa como parámetro.
Retorna los datos de configuración de un forward global (por defecto) identificado a través de los parámetros pasados.
Retorna el valor de la propiedad path de un forward global (por defecto) identificado a través de los parámetros pasados.
Retorna el valor de la propiedad content de un forward global (por defecto) identificado a través de los parámetros pasados.
Retorna los datos de configuración correspondientes a la ubicación del fichero MessageResources.
Retorna una lista de los nombres de los plug-in's configurados.
Retorna el valor del parámetro del plug-in identificado a través de los parámetros pasados.
A continuación se muestra un Diagrama de Clases que representa la jerarquía de clases Action proporcionada por el framework PORTIONS:
Clase base de la jerarquía de Actions proporcionada por el framework PORTIONS. Se trata de una clase abstracta que ofrece la funcionalidad básica que utilizarán las Actions.
Log de la clase.
Método abstracto que deberán sobreescribir las Actions concretas para ejecutar sus tareas.
éste método será invocado por el controlador de la aplicación.
Método que permite obtener el forward al que se redireccionará el flujo de la aplicación.
La implementación por defecto extrae el forward de la instancia de la clase Action que se pasa por parámetro, y si no existe, busca el forward por defecto.
Las clases hijas pueden sobreescribir este método.
Clase abstracta que representa una extensión de la clase base de la jerarquía de Actions. Implementa la siguiente máquina de estados:
Instancia de la clase net.sf.portions.controller.configuration.Action con los datos de configuración de la action.
Instancia de la clase net.sf.portions.form.PortletForm que opcionalmente (dependiendo de la configuración) puede contener los parámetros de la petición.
La petición procesada (instancia de la clase javax.portlet.PortletRequest).
La respuesta generada (instancia de la clase javax.portlet.PortletResponse).
Comprueba las precondiciones que debe cumplir la Action.
En el caso de que no se cumpla alguna precondición se debe dejar un registro de la incidencia mediante la creación de un mensaje. Esta acción provocará la redirección del flujo de ejecución hacia una página de error mediante la invocación del método findFailure().
Ejecuta la lógica de negocio de la Action.
éste método debe ser sobrescrito de forma obligatoria por aquellas Actions que hereden de la clase ExtendedPortletAction.
Comprueba las postcondiciones que debe cumplir la Action.
En el caso de que no se cumpla alguna precondición se debe dejar un registro de la incidencia mediante la creación de un mensaje. Esta acción provocará la redirección del flujo de ejecución hacia una página de error mediante la invocación del método findFailure().
Retorna una instancia de la clase Forward que redirecciona a una página de error.
La implementación por defecto obtendrá el Forward "failure" del modo (view, edit o help) que corresponda.
Retorna una instancia de la clase Forward que redirecciona a una página de éxito.
La implementación por defecto obtendrá el Forward "success" del modo (view, edit o help) que corresponda.
Encierra el tratamiento de cualquier excepción que se pueda lanzar durante la ejecución de la lógica de negocio de la Action.
La implementación por defecto del método se limita a lanzar una excepción del tipo ExecuteActionException cuyo mensaje se corresponderá con el mensaje de la excepción capturada.
Verifica la existencia de un atributo en alguno de los scopes o ámbitos posibles (request, session) del portlet. Si el atributo existe se pasará el control a un forward etiquetado con "success" y, sino, a uno etiquetado con "failure".
En la propiedad "parameter" del <action-mapping> correspondiente se indicará el scope (ámbito) y el nombre del atributo a buscar, separados por ";" (punto y coma):
parameter="application;HOURS"
Si se quiere buscar el atributo en cualquiera de los posibles ámbitos se debe utilizar un "*" (asterisco):
parameter="*;HOURS"
Elimina un atributo de uno de los scopes o ámbitos posibles (request, session) del portlet. Si el atributo existe y puede ser borrado se pasará el control a un forward etiquetado con "success" y, sino, a uno etiquetado con "failure".
En la propiedad "parameter" del <action-mapping> correspondiente se indicará el scope y el nombre del atributo a eliminar, separados por ";" (punto y coma):
parameter="application;HOURS"
Si se quiere eliminar el atributo en cualquiera de los posibles ámbitos (en este caso, el atributo sólo será eliminado del primer contexto en el que sea localizado) se utilizará un "*" (asterisco):
parameter="*;HOURS"
Permite pasar de una página JSP a otra siguiendo el flujo normal de la arquitectura (Modelo 2 de Arquitectura JSP aplicado a los portlets JSR-168). Para ello sólo es necesario configurar en el <action-mapping> correspondiente un forward "success" a la página JSP a la que se redireccionará.
Los "Forms" son javaBeans que opcionalmente se asociarán a una petición. En caso de que se defina en el fichero de configuración portlet-config.xml, dicho bean tendrá sus propiedades inicializadas con los parámetros correspondientes de la petición antes de que se ejecute la Action asociada a ésta.
Clase base de la jerarquía de Forms. Se trata de una clase abstracta que ofrece la funcionalidad básica que utilizarán los Forms.
Log de la clase.
Realiza validaciones sobre los datos cargados en las propiedades.
Actualmente sin usar por parte del controlador, se recomienda no utilizar.
Resetea los valores de las propiedades.
Establece los valores de las propiedades de la instancia actual a partir de los datos obtenidos de un ValueObject.
Retorna un objeto ValueObject cargado con los datos de la instancia actual.
<portions:messages>: muestra los mensajes generados por la aplicación (normalmente errores de validación, o errores producidos durante la ejecución).
Propiedad a la que estan asociados los mensajes que se quieren mostrar. Por defecto se mostrarán todos los mensajes, sin distinguir la propiedad a la que están asociados.
Identifica los valores de cabecera, prefijo, sufijo y pie a usar para mostrar los mensajes. Por defecto se mostrarán los determinados por las propiedades "portions.messages.header", "portions.messages.prefix", "portions.messages.sufix", "portions.messages.footer" del fichero MessageResources; en caso de especificar un valor, a dichas propiedades se les concatenará un "." (punto) seguido del identificador indicado.
<%@ taglib uri='http://java.sun.com/portlet' prefix='portlet'%>
<%@ taglib uri="/WEB-INF/tld/portions.tld" prefix="portions" %>
<portlet:defineObjects/>
<portions:messages />
<portions:getResource>: obtiene el valor asociado a una clave del fichero MessageResources.
Clave del fichero MessageResources.
<%@ taglib uri='http://java.sun.com/portlet' prefix='portlet'%>
<%@ taglib uri="/WEB-INF/tld/portions.tld" prefix="portions" %>
<portlet:defineObjects/>
<portions:getResource key="label.holaMundo" />
<portions:redirect>: realiza una redirección automática desde una JSP a una action del portlet.
Identifica los valores del identificador, y del valor y la clase css del botón de envío del formulario que permite realizar la redirección. Por defecto se mostrarán los determinados por las propiedades "portions.redirect.formId", "portions.redirect.submitValue" y "portions.redirect.submitClass" del fichero MessageResources; en caso de especificar un valor, a dichas propiedades se les concatenará un "." (punto) seguido del identificador indicado.
Indica el nombre de la action a ejecutar.
Especifica el modo del portlet a mostrar (help, edit o view).
<%@ taglib uri='http://java.sun.com/portlet' prefix='portlet'%>
<%@ taglib uri="/WEB-INF/tld/portions.tld" prefix="portions" %>
<portlet:defineObjects/>
<portions:redirect action="confirmacionAction" mode="view" />
<portions:encodeURL>: codifica una URL de un recurso estático (imagen, documento, ...) incluido en el WAR del portlet.
url a codificar.
<%@ taglib uri='http://java.sun.com/portlet' prefix='portlet'%>
<%@ taglib uri="/WEB-INF/tld/portions.tld" prefix="portions" %>
<portlet:defineObjects/>
<img src="<portions:encodeURL url="img/imagenEjemplo.gif" />" title="Imagen de ejemplo">
El framework PORTIONS incorpora un sistema de validación de formularios (basada en el proyecto Commons Validator) para el cual habrá que definir una serie de reglas de validación, y un mapeo de los campos de los formularios contra dichas reglas en uno o varios ficheros XML (comúnmente son los ficheros validation-rules.xml y validation.xml respectivamente, o simplemente el fichero validation.xml).
A continuación se muestra un ejemplo del fichero validation.xml:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE form-validation PUBLIC
"-//Apache Software Foundation//DTD Commons Validator Rules Configuration 1.3.0//EN"
"http://jakarta.apache.org/commons/dtds/validator_1_3_0.dtd">
<form-validation>
<global>
<validator name="required"
classname="net.sf.portions.validator.RequiredValidator"
method="validateRequired"
methodParams="java.lang.Object, org.apache.commons.validator.Field"
msg="error.required"/>
<validator name="mustBeSelected"
classname="net.sf.portions.validator.RequiredValidator"
method="validateRequired"
methodParams="java.lang.Object, org.apache.commons.validator.Field"
msg="error.must_select"/>
</global>
<formset>
<form name="patronForm">
<field property="patron" depends="required">
<arg key="patronForm.patron"/>
</field>
</form>
<form name="idForm">
<field property="id" depends="mustBeSelected">
<arg key="idForm.id"/>
</field>
</form>
</formset>
</form-validation>
En este ejemplo se observa como se han combinado en un único fichero las reglas de validación y el mapeo anteriormente comentados:
Si se quiere profundizar en la validación de formularios se recomienda visitar la Web del proyecto Commons Validator.
Clase: net.sf.portions.validator.RequiredValidator
Método: validateRequired
Valida la existencia de un campo del formulario y que dicho campo contenga datos.
Para la creación de tablas se hace uso de la librería DisplayTag (http://displaytag.sourceforge.net/). Esta librería permite construir una tabla HTML con funcionalidades de paginación, ordenación, etc; a partir de una colección de datos mediante un conjunto de etiquetas personalizadas.
Para compatibilizar el uso de la DisplayTag con el framework PORTIONS se incluyen en este último unas clases de soporte a esta librería. Estas clases se configurarán en el fichero displaytag.properties dando al parámetro factory.reqestHelper el valor siguiente:
factory.requestHelper=net.sf.portions.displaytag.PortletRequestHelperFactory
El framework Portions ofrece el interface "ValueObject" que deben implementar los objetos de datos (patrón Value Object). Este interface define el método toXML() que permite ver una descripción del objeto en formato XML.
Para facilitar la implementación de los objetos de datos, el framework PORTIONS incluye la clase base "BaseVO" que realiza una implementación por defecto para el método toXML() definido en el interface ValueObject.
A continuación se muestra un Diagrama de Clases que representa la jerarquía de Excepciones lanzadas por el framework PORTIONS:
Clase base de la jerarquía de Excepciones proporcionada por el framework PORTIONS. Se trata de una clase que ofrece la funcionalidad básica que utilizarán las Excepciones del framework.
Log de la clase.
Constructor de la excepción que recibe como parámetro la descripción de la causa, el lugar o el motivo que provoca el disparo de la misma.
Constructor de la excepción que recibe como parámetros la clase donde se produce, el nombre del método donde se dispara y una descripción del motivo que provoca el disparo de la excepción.
Constructor de la excepción que recibe como parámetros la excepción que provoca que se dispare esta excepción (excepción que se anidará), el lugar del código, operación o función que provoca el disparo de la excepción y el motivo, sugerencia o cualquier otro tipo de mensaje auxiliar de la excepción.
Escribe información de depuración acerca de la excepción en el log.
Proporciona la representacion en XML de la Excepcion.
La excepción ExecuteActionException será lanzada por una action si durante la ejecución de sus tareas se produce algún tipo de error o situación excepcional.
En caso de que una excepción de este tipo llegue el controlador, éste mostrará un mensaje de error en el log del portlet.
La excepción PlugInException será lanzada por un plug-in (clase que implementa el interface net.sf.portions.plugin.IPortletPlugIn) si durante la ejecución de sus tareas se produce algún tipo de error o situación excepcional que deba ser tratada por parte del controlador.
El controlador, al capturar una excepción de este tipo, obtendrá los mensajes que se hayan generado durante la ejecución del plug-in y redireccionará la ejecución a la página JSP indicada en el parámetro "input" de la action que se esté tratando.
Los mensajes son el medio a través de la cual se notificarán al usuario las causas de los errores (por ejemplo errores de validación) o las situaciones especiales que se produzcan durante la ejecución de las Actions.
El framework PORTIONS proporciona diferentes clases para el tratamiento de los mensajes (además del tag <portions:messages> ya comentado en la sección Vista):
Clase de utilidad que proporciona métodos que permiten realizar tareas comunes relativas a los mensajes generados por la aplicación.
Almacena los mensajes pasados como parámetros en sesión.
Recupera y elimina de la sesión los mensajes almacenados para almacenarlos en la request.
Determina la existencia o la no existencia de mensajes en sesión.
Clase que representa un mensaje generado por la aplicación. Representa una clave a un mensaje incluido en el fichero de MessageResources de la aplicación, y opcionalmente unos valores de reemplazo correspondientes a parámetros {0}, {1}, ... {n} de dicho mensaje.
Clave del mensaje (accesible a través del método getKey():String).
Valores de reemplazo del mensaje (accesible a través del metodo getValues():Object[]).
Constructor del mensaje que recibe como parámetro la clave correspondiente del fichero MessageResources de la aplicación.
Constructor del mensaje que recibe como parámetro la clave correspondiente del fichero MessageResources de la aplicación y los valores de reemplazo.
Retorna el valor de la propiedad key.
Retorna el valor de la propiedad values.
Colección de mensajes con soporte para una jerarquización de mensajes por 'propiedad'.
Nombre de la propiedad utilizada para almacenar mensajes globales (es decir, aquellos no relacionados a una propiedad determinada).
Constructor sin parámetros de la clase.
Constructor de la clase que añade a la nueva instancia los mensajes contenidos en otra instancia pasada como parámetro.
Añade un mensaje al conjunto de mensajes asociado a laa propiedad determinada (si es null o cadena vacía se tomará el valor PortletMessages.GLOBAL_MESSAGE).
Añade todos los mensajes de una instancia de la clase PortletMessages al conjunto de mensajes actual.
limina todos los mensajes almacenados en la instancia actual.
Determina si el conjunto actual de mensajes está vacío o no lo está.
Retorna el conjunto de todos los mensajes almacenados.
Retorna el conjunto de todos los mensajes almacenados asociados a la propiedad especificada (si es null o cadena vacía se tomará el valor PortletMessages.GLOBAL_MESSAGE).
Retorna un iterador con el conjunto de propiedades utilizados para almacenar mensajes.
Retorna el número de pares propiedad-clave añadidos.
Retorna el número de mensajes asociados a la propiedad especificada (si dicha propiedad es null, o cadena vacía, se tomará el valor PortletMessages.GLOBAL_MESSAGE).
