com.openharbor.beck.map
Interface Configuration

All Known Implementing Classes:

Choose, Mapping

public interface Configuration

Configures a mapper. Contains information that the mapper uses to guide its behavior.

To construct a Configuration, we recommend reading it from XML, using MAP_FROM_XML and an ObjectXMLReader.

This interface is read-only. Use another interface to construct or mutate a configuration.

Nested Class Summary

static class	Configuration.MarshalSelector Identifies a configuration parameter and the circumstances in which it will affect marshalling.
static class	Configuration.Selector Identifies a configuration parameter.
static class	Configuration.UnmarshalSelector Identifies a configuration parameter and the circumstances in which it will affect unmarshalling.

Field Summary

static XMLName	CLASS
static java.lang.String	EMPTY_STRING A zero-length String.
static XMLName	EXCLUDE_PROPERTIES
static XMLName	FACTORY
static XMLName	GETTER
static XMLName	IDENTIFIER
static XMLName	INCLUDE_PROPERTIES
static MapFromXML	MAP_FROM_XML The recommended mapping for unmarshalling a Configuration from XML.
static XMLName	MAPPER
static XMLName	MARSHALLER
static java.lang.String	MINIMAL_XML XML from which one can unmarshal a simple configuration.
static XMLName	MODEL
static XMLName	NAMER
static XMLThing	NO_XML Indicates the absence of any XML element or attribute.
static XMLName	PACKAGES
static XMLName	PROPERTY
static XMLName	RECEIVER
static XMLName	SETTER
static XMLName	UNMARSHALLER
static XMLName	XML

Method Summary

java.lang.Object

get(Configuration.Selector selector) Get configuration information.

Field Detail

MAP_FROM_XML

public static final MapFromXML MAP_FROM_XML

The recommended mapping for unmarshalling a Configuration from XML. This is a little tricky. To map your XML dialect to or from Java, we recommend a DefaultMapper that contains a Configuration that you read from another XML document, using this map. You can hand-craft the mapping XML, in most cases (see below), or apply your favorite XML tools to generate the mapping XML. Here's a sample mapping XML file:

<mapping>
     <choose namer="my.soap.Namer" packages="my.favorite java.lang"/>
     <when class="my.favorite.Thing">
         <choose getter="my.soap.ThingAccessor"
                 setter="my.soap.ThingAccessor"/>
     </when>
     <when ...
     <when ...
     <when property="class" class="java.lang.Class">
         <choose element="-none-"/>
     </when>
 </mapping>

Each <choose> element contains parameters that affect mapping. <choose> elements are often wrapped in a <when> element, to limit their effect to specific circumstances. These elements are ordered, with defaults at the end and more specific configuration at the beginning.

When the mapper needs a configuration parameter, it calls its Configuration, which scans the <mapping> for the desired parameter in a <choose> element, but skips over <when> elements that don't match the current circumstances. (The code isn't quite so simple, but it behaves this way.)

A <choose> element may contain these configuration parameters, as attributes:

• mapper=the mapper class name. This class must extend DefaultMapper.
• packages=a whitespace-separated list of names of packages to be searched for named classes.
• namer=the namer class name. This class must implement Namer.
• factory=the factory class name. This class must implement ObjectFactory.
• identifier=the identifier class name.
• getter=the getter class name (for marshalling to XML). This class must implement Getter.
• setter=the setter class name (for unmarshalling from XML), or "-none-" to choose BitBucketSetter. This class must implement Setter.
• unmarshaller=the unmarshaller class name (for unmarshalling from XML). This class must implement Unmarshaller.
• marshaller=the marshaller class name. This class must implement Marshaller.
• receiver=the receiver class name. This class must implement XMLReceiver.
• element=the XML element name (when mapping from Java to XML). element="-none-" is special: it means "Don't map this object to XML."
• attribute=the XML attribute name (when mapping from Java to XML)
• class=the name of the class of the current Java object.
• property=the name of the JavaBean-style property whose value is the current Java object.
• excludeProperties=a whitespace-separated list of JavaBean-style property names, which should not be marshalled to XML.
• includeProperties=a whitespace-separated list of JavaBean-style property names, which should be marshalled to XML (regardless of whether they have public getters).
• schemaLocation=the URI of an XML schema (.xsd) file. This is treated as the systemID of an external entity. (An EntityResolver may be configured to help find and read the schema file.)

  Beck uses the schema to guide how it copies data from Java to XML. Specifically, the ordering of XML elements and their namespaces will be taken from the schema, in cases where the schema specifies a simple ordering of elements. A more complicated schema (with alternative or open-ended element sequencing)

A <when> element may specify these circumstances, as attributes:

• parent.class=the name of the class (or a base class or an implemented interface) of the parent of the current Java object
• property=the name of the JavaBean-style property whose value is the current Java object.
• class=the name of the class (or a base class or an implemented interface) of the current Java object.
• direction="Java to XML" or "XML to Java"
• element=the XML element name (when mapping from XML to Java)
• attribute=the XML attribute name (when mapping from XML to Java)
• predicate=a predicate class name. This class must implement Predicate. A Predicate is useful for decision criteria that are too complex for a simple <when> element.

Each <when> attribute is evaluated as a Boolean expression. Their values are 'and'ed together; that is, a <when> element is ignored if any of its attributes evaluate to 'false'. <when> elements can be nested to make a decision tree. A simple 'or else' sequence can be expressed with consecutive <when> elements, since they are evaluated in the order they appear in the XML (and evaluation stops as soon as the desired configuration parameter is found).

Customized software may support additional attributes in <when> or <choose> elements. For example, a Predicate may interpret additional <when> attributes as decision factors.

This object is thread-safe (unlike most implementations of MapFromXML).

MINIMAL_XML

public static final java.lang.String MINIMAL_XML

XML from which one can unmarshal a simple configuration. The resulting configuration is pretty limited: you might use it as an example, but you'll probably need something more elaborate for a real application. And we recommend you place your XML in a property or file, not a String literal.

See Also:

Constant Field Values

MAPPER

public static final XMLName MAPPER

PACKAGES

public static final XMLName PACKAGES

NAMER

public static final XMLName NAMER

FACTORY

public static final XMLName FACTORY

IDENTIFIER

public static final XMLName IDENTIFIER

GETTER

public static final XMLName GETTER

SETTER

public static final XMLName SETTER

MARSHALLER

public static final XMLName MARSHALLER

UNMARSHALLER

public static final XMLName UNMARSHALLER

RECEIVER

public static final XMLName RECEIVER

CLASS

public static final XMLName CLASS

PROPERTY

public static final XMLName PROPERTY

EXCLUDE_PROPERTIES

public static final XMLName EXCLUDE_PROPERTIES

INCLUDE_PROPERTIES

public static final XMLName INCLUDE_PROPERTIES

XML

public static final XMLName XML

MODEL

public static final XMLName MODEL

NO_XML

public static final XMLThing NO_XML

Indicates the absence of any XML element or attribute. For example, Configuration.get returns this object when selector.key == XML and the configuration specifies that the object should not be marshalled. (In which case MapToXML.getXMLName should return null.)

EMPTY_STRING

public static final java.lang.String EMPTY_STRING

A zero-length String.

See Also:

Constant Field Values

Method Detail

get

public java.lang.Object get(Configuration.Selector selector)

Get configuration information. This method must be thread-safe; that is, when called concurrently by multiple threads, the object returned to each thread must be independent of the threads' order of execution. This is ordinarily achieved by not modifying any objects.

Parameters:

selector - identifies what information is wanted.

Returns:

the desired information, or null if no such information is available.