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 }