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 }