001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
003     * agreements. See the NOTICE file distributed with this work for additional information regarding
004     * copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the
005     * "License"); you may not use this file except in compliance with the License. You may obtain a
006     * copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable
007     * law or agreed to in writing, software distributed under the License is distributed on an "AS IS"
008     * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
009     * for the specific language governing permissions and limitations under the License.
010     */
011    package javax.portlet.faces;
012    
013    import javax.faces.context.FacesContext;
014    import javax.portlet.Event;
015    import javax.portlet.faces.event.EventNavigationResult;
016    
017    
018    /**
019     * The <code>BridgeEventHandler</code> interface defines the class the bridge relies
020     * on to process portlet events.  Because portlet events have arbitrary payloads
021     * the bridge provides no automated mappings to managed beans.  Instead, the bridge
022     * calls the <code>handleEvent</code> method on the <code>BridgeEventHandler</code> 
023     * instance passed to it (via a <code>PortletContext</code> attrbiute at init time.
024     * This method is expected to update any models based on the event's payload
025     * and then to perform any needed application recomputation to ensure a 
026     * consistent state.  The method is called after the <code>FacesContext</code>
027     * has been established and the <code>Lifecycle</code> has restored the view.<p>
028     * A view navigation can be affected by returning a non-null <code>EventNavigationResult</code>.
029     * Such an object will contain two <code>String</code> values: a fromAction and 
030     * an outcome.  These correspond to the from action and outcomes in Faces
031     * navigation rules.  Using this information the bridge affects the navigation
032     * by calling the Faces <code>NavigationHandler</code>.
033     */
034    
035    public interface BridgeEventHandler
036    {
037      /**
038       * Called by the bridge when it needs to process a portlet event.<p>
039       * 
040       * Because portlet events have arbitrary payloads
041       * the bridge provides no automated mappings to managed beans.  Instead, the bridge
042       * calls the <code>handleEvent</code> method on the <code>BridgeEventHandler</code> 
043       * instance passed to it (via a <code>PortletContext</code> attrbiute at init time.
044       * This method is expected to update any models based on the event's payload
045       * and then to perform any needed application recomputation to ensure a 
046       * consistent state.  The method is called after the <code>FacesContext</code>
047       * has been established and the <code>Lifecycle</code> has restored the view.<p>
048       * A view navigation can be affected by returning a non-null <code>EventNavigationResult</code>.
049       * Such an object will contain two <code>String</code> values: a fromAction and 
050       * an outcome.  These correspond to the from action and outcomes in Faces
051       * navigation rules.  Using this information the bridge affects the navigation
052       * by calling the Faces <code>NavigationHandler</code>.
053       * 
054       * @param context
055       *          current FacesContext. A Lifecycle has been acquired and the current view restored.
056       * @param event
057       *          the portlet event. Other portlet information (request/response) is accessed via the ExternalContext.
058       * @return an object containing the fromAction and outcome of any navigation that resulted from this event.
059       *         If the event doesn't cause a navigation, return null.
060       */
061      public EventNavigationResult handleEvent(FacesContext context, Event event);
062    }