View Javadoc

1   package org.apache.velocity.app.event;
2   
3   import org.apache.velocity.context.Context;
4   import org.apache.velocity.util.ContextAware;
5   
6   /*
7    * Licensed to the Apache Software Foundation (ASF) under one
8    * or more contributor license agreements.  See the NOTICE file
9    * distributed with this work for additional information
10   * regarding copyright ownership.  The ASF licenses this file
11   * to you under the Apache License, Version 2.0 (the
12   * "License"); you may not use this file except in compliance
13   * with the License.  You may obtain a copy of the License at
14   *
15   *   http://www.apache.org/licenses/LICENSE-2.0
16   *
17   * Unless required by applicable law or agreed to in writing,
18   * software distributed under the License is distributed on an
19   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
20   * KIND, either express or implied.  See the License for the
21   * specific language governing permissions and limitations
22   * under the License.    
23   */
24  
25  /**
26   *  Event handler for include type directives (e.g. <code>#include()</code>, <code>#parse()</code>)
27   *  Allows the developer to modify the path of the resource returned.
28   *
29   * @author <a href="mailto:wglass@forio.com">Will Glass-Husain</a>
30   * @version $Id: IncludeEventHandler.java 463298 2006-10-12 16:10:32Z henning $
31   */
32  public interface  IncludeEventHandler extends EventHandler
33  {
34      /**
35       * Called when an include-type directive is encountered (
36       * <code>#include</code> or <code>#parse</code>). May modify the path
37       * of the resource to be included or may block the include entirely. All the
38       * registered IncludeEventHandlers are called unless null is returned. If
39       * none are registered the template at the includeResourcePath is retrieved.
40       *
41       * @param includeResourcePath  the path as given in the include directive.
42       * @param currentResourcePath the path of the currently rendering template that includes the
43       *            include directive.
44       * @param directiveName  name of the directive used to include the resource. (With the
45       *            standard directives this is either "parse" or "include").
46       *
47       * @return a new resource path for the directive, or null to block the
48       *         include from occurring.
49       */
50      public String includeEvent( String includeResourcePath, String currentResourcePath, String directiveName );
51  
52  
53  
54      /**
55       * Defines the execution strategy for includeEvent
56       */
57      static class IncludeEventExecutor implements EventHandlerMethodExecutor
58      {
59          private Context context;
60          private String includeResourcePath;
61          private String currentResourcePath;
62          private String directiveName;
63          
64          private boolean executed = false;
65          
66          IncludeEventExecutor(
67                  Context context, 
68                  String includeResourcePath,
69                  String currentResourcePath,
70                  String directiveName)
71          {
72              this.context = context;
73              this.includeResourcePath = includeResourcePath;
74              this.currentResourcePath = currentResourcePath;
75              this.directiveName = directiveName;
76          }
77  
78          /**
79           * Call the method includeEvent()
80           *  
81           * @param handler call the appropriate method on this handler
82           */
83          public void execute(EventHandler handler)
84          {
85              IncludeEventHandler eh = (IncludeEventHandler) handler;
86              
87              if (eh instanceof ContextAware)
88                  ((ContextAware) eh).setContext(context);
89  
90              executed = true;
91              includeResourcePath = ((IncludeEventHandler) handler)
92                  .includeEvent(includeResourcePath, currentResourcePath, directiveName); 
93          }
94  
95          public Object getReturnValue()
96          {
97              return includeResourcePath;
98          }
99  
100         public boolean isDone()
101         {
102             return executed && (includeResourcePath == null);
103         }        
104         
105         
106     }
107 
108 }