AbstractContext


1   package org.apache.velocity.context;
2   
3   /*
4    * Copyright 2001,2004 The Apache Software Foundation.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.io.Serializable  ;
20  
21  import org.apache.velocity.context.Context;
22  import org.apache.velocity.context.InternalContextBase;
23  
24  /**
25   *  This class is the abstract base class for all conventional 
26   *  Velocity Context  implementations.  Simply extend this class 
27   *  and implement the abstract routines that access your preferred 
28   *  storage method.
29   *
30   *  Takes care of context chaining.
31   *
32   *  Also handles / enforces policy on null keys and values :
33   *
34   *  <ul>
35   *  <li> Null keys and values are accepted and basically dropped.
36   *  <li> If you place an object into the context with a null key, it
37   *        will be ignored and logged.
38   *  <li> If you try to place a null into the context with any key, it
39   *        will be dropped and logged.
40   *  </ul>
41   *
42   *  The default implementation of this for application use is 
43   *  org.apache.velocity.VelocityContext.
44   *
45   *  All thanks to Fedor for the chaining idea.
46   *
47   * @author <a HREF="mailto:geirm@optonline.net">Geir Magnusson Jr.</a>
48   * @author <a HREF="mailto:fedor.karpelevitch@home.com">Fedor Karpelevitch</a>
49   * @author <a HREF="mailto:jvanzyl@apache.org">Jason van Zyl</a>
50   * @version $Id: AbstractContext.java,v 1.8.8.1 2004/03/03 23:22:54 geirm Exp $
51   */
52  
53  public abstract class AbstractContext extends InternalContextBase 
54      implements Context, Serializable  
55  {
56      /**
57       *  the chained Context if any
58       */
59      private   Context  innerContext = null;
60    
61      /** 
62       *  Implement to return a value from the context storage. 
63       *  <br><br>
64       *  The implementation of this method is required for proper
65       *  operation of a Context implementation in general
66       *  Velocity use.
67       *  
68       *  @param key key whose associated value is to be returned
69       *  @return object stored in the context
70       */
71      public abstract Object   internalGet( String   key );
72  
73      /** 
74       *  Implement to put a value into the context storage.
75       *  <br><br>
76       *  The implementation of this method is required for 
77       *  proper operation of a Context implementation in
78       *  general Velocity use.
79       *
80       *  @param key key with which to associate the value
81       *  @param value value to be associated with the key
82       *  @return previously stored value if exists, or null
83       */
84      public abstract Object   internalPut( String   key, Object   value );
85  
86      /** 
87       *  Implement to determine if a key is in the storage.
88       *  <br><br>
89       *  Currently, this method is not used internally by 
90       *  the Velocity core. 
91       *
92       *   @param key key to test for existance 
93       *   @return true if found, false if not
94       */
95      public abstract boolean internalContainsKey(Object   key);
96  
97      /** 
98       *  Implement to return an object array of key 
99       *  strings from your storage.
100      *  <br><br>
101      *  Currently, this method is not used internally by
102      *  the Velocity core.
103      *
104      *  @return array of keys
105      */
106     public abstract Object  [] internalGetKeys();
107 
108     /** 
109      *  I mplement to remove an item from your storage.
110      *  <br><br>
111      *  Currently, this method is not used internally by
112      *  the Velocity core.
113      *
114      *  @param key key to remove
115      *  @return object removed if exists, else null
116      */
117     public abstract Object   internalRemove(Object   key);
118 
119     /**
120      *  default CTOR
121      */
122     public AbstractContext()
123     {
124     }        
125 
126     /**
127      *  Chaining constructor accepts a Context argument.
128      *  It will relay get() operations into this Context
129      *  in the even the 'local' get() returns null.
130      *  
131      *  @param inner context to be chained
132      */
133     public AbstractContext( Context inner )
134     {
135         innerContext = inner;
136 
137         /*
138          *  now, do a 'forward pull' of event cartridge so
139          *  it's accessable, bringing to the top level.
140          */
141 
142         if (innerContext instanceof InternalEventContext )
143         {
144             attachEventCartridge( ( (InternalEventContext) innerContext).getEventCartridge() );
145         }
146     }
147 
148     /**
149      * Adds a name/value pair to the context. 
150      * 
151      * @param key   The name to key the provided value with.
152      * @param value The corresponding value.
153      * @return Object that was replaced in the the Context if
154      *         applicable or null if not.
155      */
156     public Object   put(String   key, Object   value)
157     {
158         /*
159          * don't even continue if key or value is null
160          */
161 
162         if (key == null)
163         {
164             return null;
165         }
166         else if (value == null)
167         {
168             return null;
169         }
170         
171         return internalPut(key, value);
172     }
173 
174     /**
175      *  Gets the value corresponding to the provided key from the context.
176      *
177      *  Supports the chaining context mechanism.  If the 'local' context
178      *  doesn't have the value, we try to get it from the chained context.
179      *
180      *  @param key The name of the desired value.
181      *  @return    The value corresponding to the provided key or null if
182      *             the key param is null.
183      */
184     public Object   get(String   key)
185     {
186         /*
187          *  punt if key is null
188          */
189 
190         if (key == null)
191         {
192             return null;
193         }
194 
195         /*
196          *  get the object for this key.  If null, and we are chaining another Context
197          *  call the get() on it.
198          */
199 
200         Object   o = internalGet( key );
201 
202         if (o == null && innerContext != null)
203         {
204             o = innerContext.get( key );
205         }
206             
207         return o;
208     }        
209 
210     /**
211      *  Indicates whether the specified key is in the context.  Provided for 
212      *  debugging purposes.
213      *
214      * @param key The key to look for.
215      * @return true if the key is in the context, false if not.
216      */
217     public boolean containsKey(Object   key)
218     {
219         if (key == null)
220         {
221             return false;
222         }
223 
224         return internalContainsKey(key);
225     }        
226 
227     /**
228      *  Get all the keys for the values in the context
229      *  @return Object[] of keys in the Context. Does not return
230      *          keys in chained context.
231      */
232     public Object  [] getKeys()
233     {
234         return internalGetKeys();
235     }
236 
237     /**
238      * Removes the value associated with the specified key from the context.
239      *
240      * @param key The name of the value to remove.
241      * @return    The value that the key was mapped to, or <code>null</code> 
242      *            if unmapped.
243      */
244     public Object   remove(Object   key)
245     {
246         if (key == null)
247         {
248             return null;
249         }
250 
251         return internalRemove(key);
252     }   
253 
254     /**
255      *  returns innerContext if one is chained
256      *
257      *  @return Context if chained, <code>null</code> if not
258      */
259     public Context getChainedContext()
260     {
261         return innerContext;
262     }
263 
264 }
265 
266 
267 
268
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags