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 }