org.webmacro
Class Broker

java.lang.Object
  |
  +--org.webmacro.Broker
Direct Known Subclasses:
ServletBroker

public class Broker
extends java.lang.Object

The Broker is responsible for loading and initializing almost everything in WebMacro. It reads a set of Properties and uses them to determine which components of WebMacro should be loaded. It is also responsible for loading in things like Templates, URLs, and so forth.

By default the Broker reads a file called WebMacro.properties, searching your CLASSPATH and system CLASSPATH for it. There are constructors to allow you to specify a different location, a URL, or even just supply a properties object directly.

The most common WebMacro installation problems revolve around the Broker. Without a properly configured Broker WebMacro is unable to load templates, parse templates, fetch URLs, or perform most of its other basic functions.


Field Summary
protected  Settings _config
           
protected  Log _log
           
protected  LogSystem _ls
           
protected static java.lang.ClassLoader _myClassLoader
           
protected  java.lang.String _name
           
protected  ProfileCategory _prof
           
 PropertyOperatorCache _propertyOperators
           
protected  java.util.Hashtable _providers
           
protected static java.lang.ClassLoader _systemClassLoader
           
static java.util.WeakHashMap brokers
           
static java.lang.String SETTINGS_PREFIX
           
static java.lang.String WEBMACRO_DEFAULTS
           
static java.lang.String WEBMACRO_PROPERTIES
           
 
Constructor Summary
protected Broker()
          Equivalent to Broker("WebMacro.properties"), except that it doesn't complain if WebMacro.properties can't be found.
protected Broker(Broker dummy, java.lang.String name)
          Explicitly provide the properties that WebMacro should configure from.
protected Broker(java.lang.String fileName)
          Search the classpath for the properties file under the specified name.
 
Method Summary
 void addProvider(Provider p, java.lang.String pType)
          Register a new provider, calling its getType() method to find out what type of requests it wants to serve.
 java.lang.Class classForName(java.lang.String name)
          Load a class through the broker's class loader.
protected static Broker findBroker(java.lang.Object key)
          Find the broker for the specified partition key, if one is registered.
 java.lang.Object get(java.lang.String type, java.lang.String query)
          Look up query against a provider using its integer type handle.
 boolean getBooleanSetting(java.lang.String key)
          Access to the settings in WebMacro.properties
static Broker getBroker()
           
static Broker getBroker(java.lang.String settingsFile)
           
 java.lang.Object getBrokerLocal(java.lang.Object key)
          Get a value that was previously stored in this Broker.
 EvaluationExceptionHandler getEvaluationExceptionHandler()
          Get the EvaluationExceptionHandler
 FastWriter getFastWriter(java.io.OutputStream out, java.lang.String enctype)
          Retrieve a FastWriter from WebMacro's internal pool of FastWriters.
 int getIntegerSetting(java.lang.String key)
          Access to the settings in WebMacro.properties
 int getIntegerSetting(java.lang.String key, int defaultValue)
          Access to the settings in WebMacro.properties
 Log getLog(java.lang.String type)
          Shortcut: create a new log using the type as the description
 Log getLog(java.lang.String type, java.lang.String description)
          Get a log: the behavior of this log depends on the configuration of the broker.
 java.lang.String getName()
           
 Provider getProvider(java.lang.String type)
          Get a provider
 java.net.URL getResource(java.lang.String name)
          Get a resource (file) from the the Broker's class loader.
 java.io.InputStream getResourceAsStream(java.lang.String name)
          Get a resource (file) from the Broker's class loader
 java.lang.String getSetting(java.lang.String key)
          Access to the settings in WebMacro.properties
 Settings getSettings()
          Access to the settings in WebMacro.properties
 java.lang.Object getValue(java.lang.String type, java.lang.String query)
          Deprecated. call get(String,String) instead
protected  void init()
          Constructors should call this after they've set up the properties to set up common things like profiling, providers, etc.
protected  void initLog()
          Constructors should call this after they've set up the properties to set up the log target.
protected  void loadDefaultSettings()
           
protected  boolean loadSettings(java.lang.String name, boolean optional)
           
protected  void loadSystemSettings()
           
static void main(java.lang.String[] arg)
          Test the broker or a provider.
 Profile newProfile()
          Get a profile instance that can be used to instrument code.
protected static void register(java.lang.Object key, Broker broker)
          Used to maintain a weak map mapping the partition key to the Broker.
 void setBrokerLocal(java.lang.Object key, java.lang.Object value)
          Store a key/value in this Broker.
 void setEvaluationExceptionHandler(EvaluationExceptionHandler eeh)
          Set a new EvaluationExceptionHandler
 void shutdown()
          Shut down the broker
 java.lang.String toString()
          Explain myself
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

WEBMACRO_DEFAULTS

public static final java.lang.String WEBMACRO_DEFAULTS

WEBMACRO_PROPERTIES

public static final java.lang.String WEBMACRO_PROPERTIES

SETTINGS_PREFIX

public static final java.lang.String SETTINGS_PREFIX

brokers

public static final java.util.WeakHashMap brokers

_myClassLoader

protected static java.lang.ClassLoader _myClassLoader

_systemClassLoader

protected static java.lang.ClassLoader _systemClassLoader

_providers

protected final java.util.Hashtable _providers

_config

protected final Settings _config

_name

protected final java.lang.String _name

_ls

protected final LogSystem _ls

_propertyOperators

public final PropertyOperatorCache _propertyOperators

_log

protected Log _log

_prof

protected ProfileCategory _prof
Constructor Detail

Broker

protected Broker()
          throws InitException
Equivalent to Broker("WebMacro.properties"), except that it doesn't complain if WebMacro.properties can't be found.

Broker

protected Broker(java.lang.String fileName)
          throws InitException
Search the classpath for the properties file under the specified name.
Parameters:
fileName - Use this name instead of "WebMacro.properties"

Broker

protected Broker(Broker dummy,
                 java.lang.String name)
          throws InitException
Explicitly provide the properties that WebMacro should configure from. You also need to specify a name for this set of properties so WebMacro can figure out whether two brokers point at the same properties information.
Parameters:
config - WebMacro's configuration settings
name - Two brokers are the "same" if they have the same name
Method Detail

initLog

protected void initLog()
Constructors should call this after they've set up the properties to set up the log target. If subclasses are going to set up logging themselves, then they don't have to call it.

init

protected void init()
             throws InitException
Constructors should call this after they've set up the properties to set up common things like profiling, providers, etc.

getBroker

public static Broker getBroker()
                        throws InitException

getBroker

public static Broker getBroker(java.lang.String settingsFile)
                        throws InitException

loadDefaultSettings

protected void loadDefaultSettings()
                            throws InitException

loadSettings

protected boolean loadSettings(java.lang.String name,
                               boolean optional)
                        throws InitException

loadSystemSettings

protected void loadSystemSettings()

register

protected static void register(java.lang.Object key,
                               Broker broker)
Used to maintain a weak map mapping the partition key to the Broker. Registers a broker for a given partition key.

findBroker

protected static Broker findBroker(java.lang.Object key)
Find the broker for the specified partition key, if one is registered. Used by factory methods to ensure that there is only one broker per WM partition

getSettings

public Settings getSettings()
Access to the settings in WebMacro.properties

getSetting

public java.lang.String getSetting(java.lang.String key)
Access to the settings in WebMacro.properties

getBooleanSetting

public boolean getBooleanSetting(java.lang.String key)
Access to the settings in WebMacro.properties

getIntegerSetting

public int getIntegerSetting(java.lang.String key)
Access to the settings in WebMacro.properties

getIntegerSetting

public int getIntegerSetting(java.lang.String key,
                             int defaultValue)
Access to the settings in WebMacro.properties

addProvider

public void addProvider(Provider p,
                        java.lang.String pType)
                 throws InitException
Register a new provider, calling its getType() method to find out what type of requests it wants to serve.

getProvider

public Provider getProvider(java.lang.String type)
                     throws NotFoundException
Get a provider

getLog

public Log getLog(java.lang.String type,
                  java.lang.String description)
Get a log: the behavior of this log depends on the configuration of the broker. If your system loads from a WebMacro.properties file then look in there for details about setting up and controlling the Log.

You should try and hang on to the Log you get back from this method since creating new Log objects can be expensive. You also likely pay for IO when you use a log object.

The type you supply will be associated with your log messages in the log file.


getLog

public Log getLog(java.lang.String type)
Shortcut: create a new log using the type as the description

getFastWriter

public final FastWriter getFastWriter(java.io.OutputStream out,
                                      java.lang.String enctype)
                               throws java.io.UnsupportedEncodingException
Retrieve a FastWriter from WebMacro's internal pool of FastWriters. A FastWriter is used when writing templates to an output stream
Parameters:
out - The output stream the FastWriter should write to. Typically this will be your ServletOutputStream. It can be null if only want the fast writer to buffer the output.
enctype - the Encoding type to use

getEvaluationExceptionHandler

public EvaluationExceptionHandler getEvaluationExceptionHandler()
Get the EvaluationExceptionHandler

setEvaluationExceptionHandler

public void setEvaluationExceptionHandler(EvaluationExceptionHandler eeh)
Set a new EvaluationExceptionHandler

getResource

public java.net.URL getResource(java.lang.String name)
Get a resource (file) from the the Broker's class loader. We look first with the Broker's class loader, then with the system class loader, and then for a file.

getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String name)
Get a resource (file) from the Broker's class loader

classForName

public java.lang.Class classForName(java.lang.String name)
                             throws java.lang.ClassNotFoundException
Load a class through the broker's class loader. Subclasses can redefine or chain if they know of other ways to load a class.

newProfile

public Profile newProfile()
Get a profile instance that can be used to instrument code. This instance must not be shared between threads. If profiling is currently disabled this method will return null.

get

public java.lang.Object get(java.lang.String type,
                            java.lang.String query)
                     throws ResourceException
Look up query against a provider using its integer type handle.

setBrokerLocal

public void setBrokerLocal(java.lang.Object key,
                           java.lang.Object value)
Store a key/value in this Broker. This is a utility feature for one to save data that is specific to this instance of WebMacro.

Please remember that you probably aren't the only one storing keys in here, so be specific with your key names. Don't use names like String or Foo. Instead, use IncludeDirective.String and IncludeDirective.Foo.


getBrokerLocal

public java.lang.Object getBrokerLocal(java.lang.Object key)
Get a value that was previously stored in this Broker.
See Also:
setBrokerLocal(java.lang.Object, java.lang.Object)

getValue

public final java.lang.Object getValue(java.lang.String type,
                                       java.lang.String query)
                                throws ResourceException
Deprecated. call get(String,String) instead

Backwards compatible, calls get(String,String)

shutdown

public void shutdown()
Shut down the broker

toString

public java.lang.String toString()
Explain myself
Overrides:
toString in class java.lang.Object

getName

public java.lang.String getName()

main

public static void main(java.lang.String[] arg)
Test the broker or a provider. Reads from stdin: TYPE NAME