View Javadoc

1   /*
2    * Copyright 2003-2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.velocity.tools.generic;
18  
19  import org.apache.velocity.context.Context;
20  
21  /***
22   * Tool for working with <code>null</code> in Velocity templates.
23   * It provides a method to set a VTL reference back to <code>null</code>.
24   * Also provides methods to check if a VTL reference is <code>null</code> or not.
25   * <p>
26   *   NOTE: These examples assume you have placed an
27   *   instance of the current context within itself as 'ctx'.
28   *   And, of course, the NullTool is assumed to be available as 'null'.
29   * </p>
30   * <p><pre>
31   * Example uses:
32   *  $foo                              -> bar
33   *  $null.isNull($foo)                -> false
34   *  $null.isNotNull($foo)             -> true
35   *
36   *  $null.setNull($ctx, "foo")
37   *  $foo                              -> $foo (null)
38   *  $null.isNull($foo)                -> true
39   *  $null.isNotNull($foo)             -> false
40   *
41   *  $null.set($ctx, $foo, "hoge")
42   *  $foo                              -> hoge
43   *  $null.set($ctx, $foo, $null.null)
44   *  $foo                              -> $foo (null)
45   * </pre></p>
46   *
47   * <p>This tool is entirely threadsafe, and has no instance members.
48   * It may be used in any scope (request, session, or application).
49   * </p>
50   *
51   * @author <a href="mailto:shinobu@ieee.org">Shinobu Kawai</a>
52   * @version $Id: $
53   */
54  public class NullTool
55  {
56  
57      /***
58       * Default constructor.
59       */
60      public NullTool()
61      {
62      }
63  
64      /***
65       * Sets the given VTL reference back to <code>null</code>.
66       * @param context the current Context
67       * @param key the VTL reference to set back to <code>null</code>.
68       */
69      public void setNull(Context context, String key)
70      {
71          if (this.isNull(context))
72          {
73              return;
74          }
75          context.remove(key);
76      }
77  
78      /***
79       * Sets the given VTL reference to the given value.
80       * If the value is <code>null</code>,
81       * the VTL reference is set to <code>null</code>.
82       * @param context the current Context
83       * @param key the VTL reference to set.
84       * @param value the value to set the VTL reference to.
85       */
86      public void set(Context context, String key, Object value)
87      {
88          if (this.isNull(context))
89          {
90              return;
91          }
92          if (this.isNull(value))
93          {
94              this.setNull(context, key);
95              return;
96          }
97          context.put(key, value);
98      }
99  
100     /***
101      * Checks if a VTL reference is <code>null</code>.
102      * @param object the VTL reference to check.
103      * @return <code>true</code> if the VTL reference is <code>null</code>,
104      *          <code>false</code> if otherwise.
105      */
106     public boolean isNull(Object object)
107     {
108         return object == null;
109     }
110 
111     /***
112      * Checks if a VTL reference is not <code>null</code>.
113      * @param object the VTL reference to check.
114      * @return <code>true</code> if the VTL reference is not <code>null</code>,
115      *          <code>false</code> if otherwise.
116      */
117     public boolean isNotNull(Object object)
118     {
119         return !this.isNull(object);
120     }
121 
122     /***
123      * A convinient method which returns <code>null</code>.
124      * Actually, this tool will work the same without this method,
125      * because Velocity treats non-existing methods as null. :)
126      * @return <code>null</code>
127      */
128     public Object getNull()
129     {
130         return null;
131     }
132 
133 }