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  package org.apache.myfaces.view.facelets.pool;
20  
21  import javax.faces.component.UIViewRoot;
22  import javax.faces.context.FacesContext;
23  import org.apache.myfaces.buildtools.maven2.plugin.builder.annotation.JSFWebConfigParam;
24  import org.apache.myfaces.view.facelets.tag.jsf.FaceletState;
25  
26  /**
27   * This class defines the necessary operations that a view pool should comply in
28   * order to be used by MyFaces.
29   * 
30   * <p>A View Pool is a set of initialized views that are kept ready to use. The idea 
31   * is reset and reuse views taking advantage of existing JSF 2.0 Partial State 
32   * Saving algorithm with some small additions to component's saveState() method.
33   * </p>
34   * <p>This technique works by these reasons:
35   * </p>
36   * <ul>
37   * <li>A view is composed by many small objects that are created multiple times per
38   * each request, and the time spent creating these objects is usually larger than 
39   * the time used to traverse the component tree.</li>
40   * <li>The structure of a view usually does not change over application lifetime.</li>
41   * <li>The "delta state" or in other words the elements that change in view are
42   * small compared with the elements that does not change.</li>
43   * </ul>
44   * <p>
45   * The implementation proposed uses a lock free view pool structure with soft or
46   * weak references. The lock free view pool ensures fast access and the soft or weak
47   * references ensured the garbage collection algorithm is not affected by the view
48   * pool.
49   * </p>
50   *
51   * @author Leonardo Uribe
52   */
53  public abstract class ViewPool
54  {
55      /**
56       * Defines the number of views to be hold per each view metadata definition.
57       * By default is 5. 
58       * 
59       * Usually a view is defined by its viewId, locale, renderKitId
60       * and active contracts. If a view shares the same values for these parameters
61       * belongs to the same group that can be pooled.
62       */
63      @JSFWebConfigParam(defaultValue="5", tags="performance")
64      public static final String INIT_PARAM_VIEW_POOL_MAX_POOL_SIZE =
65              "org.apache.myfaces.VIEW_POOL_MAX_POOL_SIZE";
66      public static final int INIT_PARAM_VIEW_POOL_MAX_POOL_SIZE_DEFAULT = 5;
67      
68      /**
69       * Defines the limit of the views that cannot be reused partially.
70       */
71      @JSFWebConfigParam(defaultValue="2", tags="performance")
72      public static final String INIT_PARAM_VIEW_POOL_MAX_DYNAMIC_PARTIAL_LIMIT =
73              "org.apache.myfaces.VIEW_POOL_MAX_DYNAMIC_PARTIAL_LIMIT";
74      public static final int INIT_PARAM_VIEW_POOL_MAX_DYNAMIC_PARTIAL_LIMIT_DEFAULT = 2;
75      
76      /**
77       * Defines the type of memory reference that is used to hold the view into memory. By
78       * default a "soft" reference is used. 
79       */
80      @JSFWebConfigParam(defaultValue="soft", expectedValues="weak,soft", tags="performance")
81      public static final String INIT_PARAM_VIEW_POOL_ENTRY_MODE =
82              "org.apache.myfaces.VIEW_POOL_ENTRY_MODE";
83      public static final String ENTRY_MODE_SOFT = "soft";
84      public static final String ENTRY_MODE_WEAK = "weak";
85      public static final String INIT_PARAM_VIEW_POOL_ENTRY_MODE_DEFAULT = ENTRY_MODE_SOFT;
86      
87      /**
88       * Defines if the view pool uses deferred navigation to recycle views when navigation
89       * is performed. The difference is a normal navigation is not done when the broadcast is
90       * done but at the end of invoke application phase.
91       */
92      @JSFWebConfigParam(defaultValue="false", expectedValues="true, false", tags="performance")
93      public static final String INIT_PARAM_VIEW_POOL_DEFERRED_NAVIGATION =
94              "org.apache.myfaces.VIEW_POOL_DEFERRED_NAVIGATION";    
95      
96      /**
97       * Indicate if the view pool uses deferred navigation.
98       * 
99       * @return 
100      */
101     public abstract boolean isDeferredNavigationEnabled();
102     
103     public abstract void storeStaticViewStructureMetadata(FacesContext context, 
104         UIViewRoot root, FaceletState faceletState);
105     
106     public abstract ViewStructureMetadata retrieveStaticViewStructureMetadata(FacesContext context,
107             UIViewRoot root);
108     
109     public abstract void pushStaticStructureView(FacesContext context, UIViewRoot root);
110 
111     public abstract void pushPartialStructureView(FacesContext context, UIViewRoot root);
112     
113     public abstract ViewEntry popStaticOrPartialStructureView(FacesContext context, UIViewRoot root);
114 
115     public abstract boolean isWorthToRecycleThisView(FacesContext context, UIViewRoot root);
116     
117     public abstract void storeDynamicViewStructureMetadata(FacesContext context, 
118             UIViewRoot root, FaceletState faceletState);
119     
120     public abstract ViewStructureMetadata retrieveDynamicViewStructureMetadata(FacesContext context,
121             UIViewRoot root, FaceletState faceletState);
122 
123     public abstract void pushDynamicStructureView(FacesContext context, UIViewRoot root, 
124             FaceletState faceletDynamicState);
125     
126     public abstract ViewEntry popDynamicStructureView(FacesContext context, UIViewRoot root,
127             FaceletState faceletDynamicState);
128 
129 }