View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one
    3    * or more contributor license agreements.  See the NOTICE file
    4    * distributed with this work for additional information
    5    * regarding copyright ownership.  The ASF licenses this file
    6    * to you under the Apache License, Version 2.0 (the
    7    * "License"); you may not use this file except in compliance
    8    * with the License.  You may obtain a copy of the License at
    9    *
    10   *   http://www.apache.org/licenses/LICENSE-2.0
    11   *
    12   * Unless required by applicable law or agreed to in writing,
    13   * software distributed under the License is distributed on an
    14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    15   * KIND, either express or implied.  See the License for the
    16   * specific language governing permissions and limitations
    17   * under the License.
    18   */
    19
    20  package org.apache.myfaces.orchestra.viewController;
    21
    22  /**
    23   * Route per-view lifecycle events to the correct user methods.
    24   * <p>
    25   * The name "view" is used for the resource that the user has accessed. For example
    26   * with JSF either one or two views are accessed per user request; possibly a "postback"
    27   * and always a "render" view. Orchestra adaptors for other UI frameworks select
    28   * an interpretation of the name "view" appropriate for that framework.
    29   * <p>
    30   * Orchestra retrieves a concrete implementation of this interface and invokes it at the
    31   * appropriate processing phases. Exactly what those phases are depend upon the underlying
    32   * UI framework. The concrete ViewControllerManager is then responsible for determining
    33   * which beans should receive callbacks (based upon the resource that the user has accessed)
    34   * <p>
    35   * Orchestra provides a default implementation of this interface; see
    36   * {@link DefaultViewControllerManager}.
    37   *
    38   * <h2>Defining your own ViewControllerManager</h2>
    39   *
    40   * If you would like to customise the way beans are located for a view, or which methods
    41   * are invoked on them then either
    42   * <ul>
    43   * <li>Implement this interface directly, or
    44   * <li>Subclass {@link AbstractViewControllerManager} (the recommended way).
    45   * </ul>
    46   * <p>
    47   * To activate your custom manager, configure it as a managed bean (preferably in
    48   * application or singleton scope), using the bean-name
    49   * <code>org.apache.myfaces.orchestra.viewController.ViewControllerManager</code>
    50   * (see constant {@link ViewControllerManager#VIEW_CONTROLLER_MANAGER_NAME}).
    51   *
    52   * <h2>How the ViewControllerManager is invoked</h2>
    53   *
    54   * Each UI framework needs to ensure that the ViewControllerManager is retrieved via the
    55   * special name shown above, and invoked at appropriate times. For example, for JSF
    56   * see class @{org.apache.myfaces.orchestra.viewController.jsf.ViewControllerPhaseListener};
    57   * this is automatically configured for JSF applications when the orchestra jarfile is
    58   * placed in the classpath.
    59   */
    60  public interface ViewControllerManager
    61  {
    62      public final static String VIEW_CONTROLLER_MANAGER_NAME = ViewControllerManager.class.getName();
    63
    64      public Object getViewController(String viewId);
    65      public String getViewControllerName(String viewId);
    66
    67      /**
    68       * Check whether any conversations required for the specified view currently exist.
    69       * <p>
    70       * TODO: Consider renaming this method. It is very Orchestra-specific, although this
    71       * ViewController framework is supposed to be generic. In fact this method
    72       * is really just a "validate view" hook, and one of the validations that can be hooked
    73       * in here is a conversation-check.
    74       */
    75      public void assertConversationState(String viewId);
    76
    77      /**
    78       * This method is guaranteed to be called before any other lifecycle method (ie any of
    79       * the other execute* methods on this interface. It is also guaranteed to be called
    80       * before any expression in a page is evaluated.
    81       * <p>
    82       * For component-based frameworks, the component tree may not yet exist.
    83       */
    84      public void executeInitView(String viewId);
    85
    86      /**
    87       * This method is called at most once per request for each view.
    88       * <p>
    89       * For component-based frameworks, this method gets called after all components have
    90       * transferred their state into associated backing beans. If validation errors have
    91       * occurred within the view, then this method is not invoked.
    92       */
    93      public void executePreProcess(String viewId);
    94
    95      /**
    96       * This method is called just before a view is required to render its representation
    97       * back to the user.
    98       * <p>
    99       * If a view X handles a "postback" event, and then navigates to a different view Y then
    100      * this callback does not occur for the controller bean for view X, but does get invoked
    101      * for the controller bean for view Y.
    102      * <p>
    103      * For component-based frameworks, the component tree may not yet exist at the time this
    104      * method is invoked.
    105      */
    106     public void executePreRenderView(String viewId);
    107
    108     // TODO: implement an endView callback too (and corresponding annotation).
    109
    110     // TODO: implement isPostback() for JSF1.1 users? This is of course built-in for JSF1.2 users...
    111 }