KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sapia > gumby > RenderContext


1 package org.sapia.gumby;
2
3 import java.io.File JavaDoc;
4 import java.io.FileInputStream JavaDoc;
5 import java.io.IOException JavaDoc;
6 import java.io.InputStream JavaDoc;
7
8 import org.sapia.gumby.factory.GumbyObjectFactory;
9 import org.sapia.gumby.view.View;
10 import org.sapia.util.xml.confix.Dom4jProcessor;
11
12 /**
13  * An instance of this class holds tag definitions (in object form) and its own
14  * environment. It can be created through a <code>RenderContextFactory</code>
15  * or as a child of another instance of this class.
16  * <p>
17  * If it is created as a child of another context, it inherits the tag
18  * definitions and the environment of that context.
19  * <p>
20  * Instances of this class can be shared between multiple threads.
21  *
22  * @see org.sapia.gumby.GuiEnv
23  * @see org.sapia.gumby.RenderContextFactory
24  * @see #newChildInstance()
25  *
26  * @author Yanick Duchesne
27  *
28  * <dl>
29  * <dt><b>Copyright: </b>
30  * <dd>Copyright &#169; 2002-2005 <a HREF="http://www.sapia-oss.org">Sapia Open
31  * Source Software </a>. All Rights Reserved.</dd>
32  * </dt>
33  * <dt><b>License: </b>
34  * <dd>Read the license.txt file of the jar or visit the <a
35  * HREF="http://www.sapia-oss.org/license.html">license page </a> at the Sapia
36  * OSS web site</dd>
37  * </dt>
38  * </dl>
39  */
40 public class RenderContext {
41
42   private Settings _settings;
43   private GuiEnv _env;
44   private GumbyObjectFactory _fac;
45
46   RenderContext(GumbyObjectFactory parent, GuiEnv env, Settings settings) {
47     _fac = new GumbyObjectFactory(parent, this);
48     _settings = settings;
49     _env = env;
50   }
51
52   /**
53    * Returns the global environment object that this instance holds.
54    *
55    * @return a <code>GuiEnv</code> instance.
56    */
57   public GuiEnv getEnv() {
58     return _env;
59   }
60
61   /**
62    * @return the <code>Settings</code> that this instance holds.
63    */
64   public Settings getSettings() {
65     return _settings;
66   }
67
68   /**
69    * This method returns a context that is a "child" of this instance: the
70    * child's environment will inherit its parent's. All scopes declared in the
71    * parent will thus be available to the child. All new scopes that do not yet
72    * exist in the parent will be created only in the child's environment (and
73    * will not be visible from the parent).
74    * <p>
75    * Similarly, all tags defined as part of the child will be visible only from
76    * the child downwards - if contexts are also created from the child and so
77    * on.
78    * <p>
79    * Creating different contexts with this method allows inheriting from the
80    * parent's environment and separating different instances when usage dictates
81    * it (for example, in a multithreaded context).
82    * <p>
83    * This is especially usefull when used in conjunction with views: the views
84    * can be created in isolation from one another, without risking naming
85    * conflicts and other side effects.
86    *
87    * @see org.sapia.gumby.view.View
88    *
89    * @return a new <code>RenderContext</code>.
90    */
91   public RenderContext newChildInstance() {
92     return new RenderContext(_fac, new DefaultGuiEnv(_env), new Settings(
93         _settings));
94   }
95
96   /**
97    * Internally creates a view, maps as a scope under the given name, and
98    * returns it.
99    * <p>
100    * Calling this method as the same effect as the following code:
101    *
102    * <pre>
103    * View v = new View(context);
104    * context.getEnv().addScope(&quot;someScope&quot;, v);
105    * </pre>
106    *
107    * @param scope
108    * the name of a scope.
109    * @return a <code>View</code>.
110    */
111   public View createView(String JavaDoc scope) {
112     View v = new View(this);
113     _env.addScope(scope, v);
114     return v;
115   }
116
117   /**
118    * @param xmlDesc
119    * the <code>InputStream</code> corresponding to an XML descriptor.
120    * @return the rendered <code>Object</code>.
121    * @throws Exception
122    * if a problem occurs while rendering.
123    */
124   public Object JavaDoc render(InputStream JavaDoc xmlDesc) throws Exception JavaDoc {
125     Dom4jProcessor proc = new Dom4jProcessor(_fac);
126     return proc.process(xmlDesc);
127   }
128
129   /**
130    * @param parent
131    * <code>Object</code> that is intented to be the parent of the
132    * rendered root objects.
133    * @param xmlDesc
134    * the <code>InputStream</code> corresponding to an XML descriptor.
135    * @throws Exception
136    * if a problem occurs while rendering.
137    */
138   public void render(Object JavaDoc parent, InputStream JavaDoc xmlDesc) throws Exception JavaDoc {
139     Dom4jProcessor proc = new Dom4jProcessor(_fac);
140     proc.process(parent, xmlDesc);
141   }
142
143   /**
144    * @see #render(InputStream)
145    */
146   public Object JavaDoc render(File JavaDoc xmlDesc) throws Exception JavaDoc {
147     return render(new FileInputStream JavaDoc(xmlDesc));
148   }
149
150   /**
151    * @see #render(Object, InputStream)
152    */
153   public void render(Object JavaDoc parent, File JavaDoc xmlDesc) throws Exception JavaDoc {
154     render(parent, new FileInputStream JavaDoc(xmlDesc));
155   }
156
157   /**
158    * Loads the definitions corresponding to the givens stream within this
159    * context. The definitions will be visible to all descendants of this
160    * context.
161    *
162    * @param is
163    * an <code>InputStream</code> corresponding to XML object
164    * definitions.
165    * @throws Exception
166    * if a problem occurs while loading the definitions.
167    */
168   public void loadDefinitions(InputStream JavaDoc is) throws Exception JavaDoc {
169     if(is != null) {
170       try {
171         Dom4jProcessor proc = new Dom4jProcessor(_fac);
172         proc.process(new Object JavaDoc(), is);
173       } finally {
174         try {
175           is.close();
176         } catch(IOException JavaDoc e) {
177         }
178       }
179     }
180   }
181
182 }
183
Popular Tags