BlockContext


1   /*
2    * Copyright (C) The Apache Software Foundation. All rights reserved.
3    *
4    * This software is published under the terms of the Apache Software License
5    * version 1.1, a copy of which has been included with this distribution in
6    * the LICENSE.txt file.
7    */
8   package org.apache.avalon.phoenix;
9   
10  import java.io.File  ;
11  import java.io.InputStream  ;
12  import org.apache.avalon.framework.context.Context;
13  import org.apache.avalon.framework.logger.Logger;
14  
15  /**
16   * Context via which Blocks communicate with container.
17   *
18   * @author <a HREF="mailto:peter at apache.org">Peter Donald</a>
19   */
20  public interface BlockContext
21      extends Context
22  {
23      String   APP_NAME = "app.name";
24      String   APP_HOME_DIR = "app.home";
25      String   NAME = "block.name";
26  
27      /**
28       * Base directory of .sar application.
29       *
30       * TODO: Should this be getHomeDirectory() or getWorkingDirectory() or other?
31       * TODO: Should a Block be able to declare it doesn't use the Filesystem? If
32       * it declares this then it would be an error to call this method.
33       *
34       * @return the base directory
35       */
36      File   getBaseDirectory();
37  
38      /**
39       * Retrieve name of block.
40       *
41       * @return the name of block
42       */
43      String   getName();
44  
45      /**
46       * A block can request that the application it resides in be
47       * shut down. This method will schedule the blocks application
48       * for shutdown. Note that this is just a request and the kernel
49       * may or may not honour the request (by default the request will
50       * be honored).
51       */
52      void requestShutdown();
53  
54      /**
55       * Retrieve a resource from the SAR file. The specified
56       * name is relative the root of the archive. So you could
57       * use it to retrieve a html page from within sar by loading
58       * the resource named "data/main.html" or similar.
59       * Names may be prefixed with '/' character.
60       *
61       * @param name the name of resource
62       * @return the InputStream for resource or null if no such resource
63       */
64      InputStream   getResourceAsStream( String   name );
65  
66      /**
67       * Retrieve logger coresponding to named category.
68       *
69       * @return the logger
70       * @deprecated This allows block writers to "break-out" of their logging
71       *             hierarchy which is considered bad form. Replace by
72       *             Logger.getChildLogger(String) where original logger is aquired
73       *             via AbstractLogEnabled.
74       */
75      Logger getLogger( String   name );
76  
77      /**
78       * Retrieve the proxy for this object.
79       * Each Block is referenced by other Blocks via their Proxy. When Phoenix
80       * shuts down the Block, it can automatically invalidate the proxy. Thus
81       * any attempt to call a method on a "dead"/shutdown object will result in
82       * an {@link IllegalStateException}. This is desirable as it will
83       * stop objects from using the Block when it is in an invalid state.
84       *
85       * <p>The proxy also allows Phoenix to associate "Context" information with
86       * the object. For instance, a {@link Block} may expect to run with a
87       * specific ContextClassLoader set. However if this Block were to be passed
88       * to another component that processed the Block in a thread that did not
89       * have the correct context information setup, then the Block could fail
90       * to perform as expected. By passing the proxy instead, the correct context
91       * information is maintained by Phoenix.</p>
92       *
93       * <p>Note that only interfaces that the Block declares as offered services
94       * will actually be implemented by the proxy.</p>
95       */
96      //Object getProxy();
97  
98      /**
99       * This method is similar to {@link #getProxy()} except that it operates
100      * on arbitrary objects. It will in effect proxy all interfaces that the
101      * component supports.
102      *
103      * <p>Proxying arbitrary objects is useful for the same reason it is useful
104      * to proxy the Block. Thus it is recomended that when needed you pass
105      * Proxys of objects to minimize the chance of incorrect behaviour.</p>
106      */
107     //Object getProxy( Object other );
108 
109     /**
110      * This method generates a Proxy of the specified object using the
111      * specified interfaces. In other respects it is identical to
112      * getProxy( Object other )
113      */
114     //Object getProxy( Object other, Class[] interfaces );
115 
116     /**
117      * This method gives you access to a named ClassLoader. The ClassLoaders
118      * for an application are declared in the <tt>environment.xml</tt>
119      * descriptor.
120      */
121     //ClassLoader getClassLoader( String name );
122 
123     /**
124      * Retrieve the MBeanServer for this application.
125      *
126      * NOTE: Unsure if this will ever be implemented
127      * may be retrievable via CM instead, or perhaps in
128      * a directory or whatever.
129      */
130     //MBeanServer getMBeanServer();
131 }
132
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags