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 685685 2008-08-13 21:43:27Z nbubna $
31   * @since 1.5
32   */
33  public interface  IncludeEventHandler extends EventHandler
34  {
35      /**
36       * Called when an include-type directive is encountered (
37       * <code>#include</code> or <code>#parse</code>). May modify the path
38       * of the resource to be included or may block the include entirely. All the
39       * registered IncludeEventHandlers are called unless null is returned. If
40       * none are registered the template at the includeResourcePath is retrieved.
41       *
42       * @param includeResourcePath  the path as given in the include directive.
43       * @param currentResourcePath the path of the currently rendering template that includes the
44       *            include directive.
45       * @param directiveName  name of the directive used to include the resource. (With the
46       *            standard directives this is either "parse" or "include").
47       *
48       * @return a new resource path for the directive, or null to block the
49       *         include from occurring.
50       */
51      public String includeEvent( String includeResourcePath, String currentResourcePath, String directiveName );
52  
53  
54  
55      /**
56       * Defines the execution strategy for includeEvent
57       */
58      static class IncludeEventExecutor implements EventHandlerMethodExecutor
59      {
60          private Context context;
61          private String includeResourcePath;
62          private String currentResourcePath;
63          private String directiveName;
64          
65          private boolean executed = false;
66          
67          IncludeEventExecutor(
68                  Context context, 
69                  String includeResourcePath,
70                  String currentResourcePath,
71                  String directiveName)
72          {
73              this.context = context;
74              this.includeResourcePath = includeResourcePath;
75              this.currentResourcePath = currentResourcePath;
76              this.directiveName = directiveName;
77          }
78  
79          /**
80           * Call the method includeEvent()
81           *  
82           * @param handler call the appropriate method on this handler
83           */
84          public void execute(EventHandler handler)
85          {
86              IncludeEventHandler eh = (IncludeEventHandler) handler;
87              
88              if (eh instanceof ContextAware)
89                  ((ContextAware) eh).setContext(context);
90  
91              executed = true;
92              includeResourcePath = ((IncludeEventHandler) handler)
93                  .includeEvent(includeResourcePath, currentResourcePath, directiveName); 
94          }
95  
96          public Object getReturnValue()
97          {
98              return includeResourcePath;
99          }
100 
101         public boolean isDone()
102         {
103             return executed && (includeResourcePath == null);
104         }        
105         
106         
107     }
108 
109 }