uk.ac.sheffield.jast

Class Metadata

java.lang.Object

uk.ac.sheffield.jast.Metadata

public class Metadata
extends java.lang.Object

Metadata records all XML-to-Java bindings and stores all XML metadata that is not part of the Java model. A Metadata object is created by ASTReader (or ASTBuilder) when unmarshalling an XML input source. It stores all the mappings from XML names to Java names and stores as metadata all other XML properties that do not form a logical part of the Java model. The same Metadata object may be given to an ASTWriter, to ensure that the same mappings and metadata are restored when the model is marshalled to an XML output sink. Alternatively, a suitable Metadata object may be created by program, before a generated model is first output to an XML sink.

Metadata stores information in a number of maps, relating XML name tokens to Java class names and Java field names. Metadata supports the conversion of XML name tokens, which allow a more liberal syntax, to Java name tokens with a more restricted syntax. Metadata also records bindings from XML namespaces to Java packages, such that XML elements from different XML namespaces may be bound to Java classes from different associated Java packages. Each bound namespace ID relates to a single Java package, which must come from a specified Internet DNS domain. The XML-to-Java bindings may be declared in Java programs, or read from the XML input source as XML processing instructions; and the same processing instructions are created when writing a Java model to an XML output sink.

All other XML properties, such as XML version and character encoding, XML doctype, schema, or stylesheet declarations and all XML namespace-to-URI mappings are stored as general metadata properties.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.Map<java.lang.String,java.lang.String>	javaClassMap The map from XML name tokens to Java class names.
private java.util.Map<java.lang.String,java.lang.String>	javaDomainMap The map from Java package prefixes to domain names.
private java.util.Map<java.lang.String,java.lang.String>	javaFieldMap The map from XML name tokens to Java field names.
private java.util.Map<java.lang.String,java.lang.String>	javaPackageMap The map from XML namespace prefixes to Java package names.
private java.util.Map<java.lang.String,java.lang.String>	nameTokenMap The inverse map from Java class or field names to XML name tokens.
private java.util.Map<java.lang.String,java.lang.String>	propertyMap The map storing all other attributes as metadata.

Constructor Summary

Constructors

Constructor and Description
Metadata() Creates a Metadata object.

Method Summary

Modifier and Type	Method and Description
void	addDomain(java.lang.String domain) Adds a DNS domain name to the set of recognised domain names.
void	bindNamespace(java.lang.String namespace, java.lang.String packageName) Associates a short XML namespace identifier with a Java package name in the namespace-to-package bindings.
private void	checkDomainName(java.lang.String domainName) Validates the syntax of a domain name or Java package name.
private void	checkNamespaceID(java.lang.String namespace) Validates the syntax of a short XML namespace identifier.
private java.lang.String	createNamespaceURI(java.lang.String namespace) Creates an XML namespace URI for a short XML namespace identifier.
java.util.Set<java.lang.String>	getAttributeNames() Returns the set of XML attribute names that were previously mapped to Java field identifiers.
java.util.Set<java.lang.String>	getElementNames() Returns the set of XML element names that were previously mapped to Java class identifiers.
private java.lang.String	getNamespacePrefix(java.lang.String packageID) Returns the short XML namespace prefix used to qualify XML elements representing objects from the given Java package.
java.util.Set<java.lang.String>	getNamespaces() Returns the set of short XML namespace identifiers that were mapped to Java packages in the namespace-to-package bindings.
java.util.Set<java.lang.String>	getProperties() Returns the set of XML metadata attributes that were previously stored as properties of this Metadata.
java.lang.String	getProperty(java.lang.String identifier) Retrieves the value of an XML metadata attribute.
void	processEntities(Lexicon lexicon, java.lang.String encoding) Processes the external and internal grammar subsets in order to find any extra entity definitions.
void	setProperty(java.lang.String identifier, java.lang.String value) Stores the value of an XML metadata attribute.
java.lang.String	toJavaClassID(java.lang.String nameToken) Converts an XML name token into a Java class identifier.
java.lang.String	toJavaFieldID(java.lang.String nameToken) Converts an XML name token into a Java field identifier.
private java.lang.String	toJavaIdentifier(java.lang.String nameToken, boolean isType) Converts an XML name token into a legal Java identifier.
java.lang.String	toJavaPackage(java.lang.String namespace) Returns the name of the Java package associated with a given short XML namespace identifier in the namespace-to-package bindings.
java.lang.String	toNamespaceURI(java.lang.String namespace) Returns the full XML namespace URI associated with a given short XML namespace identifier in the Metadata properties.
java.lang.String	toNameToken(java.lang.String javaName) Converts a Java class or field identifer back into an XML name token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

javaClassMap

private java.util.Map<java.lang.String,java.lang.String> javaClassMap

The map from XML name tokens to Java class names.

javaFieldMap

private java.util.Map<java.lang.String,java.lang.String> javaFieldMap

The map from XML name tokens to Java field names.

nameTokenMap

private java.util.Map<java.lang.String,java.lang.String> nameTokenMap

The inverse map from Java class or field names to XML name tokens.

javaPackageMap

private java.util.Map<java.lang.String,java.lang.String> javaPackageMap

The map from XML namespace prefixes to Java package names.

javaDomainMap

private java.util.Map<java.lang.String,java.lang.String> javaDomainMap

The map from Java package prefixes to domain names.

propertyMap

private java.util.Map<java.lang.String,java.lang.String> propertyMap

The map storing all other attributes as metadata. This could include declaration information, namespace URIs, stylesheet locations.

Constructor Detail

Metadata

public Metadata()

Creates a Metadata object. Initialises a number of maps.

Method Detail

getProperties

public java.util.Set<java.lang.String> getProperties()

Returns the set of XML metadata attributes that were previously stored as properties of this Metadata. These are all XML attributes that do not logically form part of the AST model, such as the XML version, or encoding, or the names and locations of stylesheets, doctypes, schemas or namespace URIs.

Returns:

a set of XML metadata attributes.

getProperty

public java.lang.String getProperty(java.lang.String identifier)

Retrieves the value of an XML metadata attribute. These include the XML version, or encoding, or the names and locations of stylesheets, doctypes, schemas or namespace URIs. Any XML attribute that is not part of the AST model is stored as a metadata attribute.

Parameters:

identifier - the name of the attribute.

Returns:

the value of the attribute.

setProperty

public void setProperty(java.lang.String identifier,
                        java.lang.String value)

Stores the value of an XML metadata attribute. These include the XML version, or encoding, or the names and locations of stylesheets, doctypes, schemas or namespace URIs. Any XML attribute that is not part of the AST model is stored as a metadata attribute. Each metadata attribute may only be bound to one value. Any rebinding will replace the earlier binding.

Parameters:

identifier - the name of the attribute.

value - the value of the attribute.

toJavaIdentifier

private java.lang.String toJavaIdentifier(java.lang.String nameToken,
                                          boolean isType)

Converts an XML name token into a legal Java identifier. XML syntax is more liberal than Java syntax, accepting more kinds of character. If the XML name token contains any underscore, hyphen or dot, this character is removed and the following character is converted to upper case, as at Java word boundaries. The resulting Java identifier is capitalised (for a type name), otherwise it starts with a lower case letter (for a field name), as determined by the flag argument.

Parameters:

nameToken - an XML name token.

isType - flag indicating a type (when true) or field (when false).

Returns:

a normalised Java identifier.

getElementNames

public java.util.Set<java.lang.String> getElementNames()

Returns the set of XML element names that were previously mapped to Java class identifiers.

Returns:

the set of XML element names.

getAttributeNames

public java.util.Set<java.lang.String> getAttributeNames()

Returns the set of XML attribute names that were previously mapped to Java field identifiers.

Returns:

the set of XML attribute names.

toJavaClassID

public java.lang.String toJavaClassID(java.lang.String nameToken)

Converts an XML name token into a Java class identifier. If the XML name token starts with a namespace prefix, uses this to discover the package name for the class. Converts the short name into a legal Java class identifier (in "CapitalCase") and, if a package name was found, prepends this to the Java class identifier. Caches the resulting bi-directional mapping in this Metadata.

Parameters:

nameToken - the XML name token.

Returns:

the Java class identifier.

toJavaFieldID

public java.lang.String toJavaFieldID(java.lang.String nameToken)

Converts an XML name token into a Java field identifier. If the XML name token starts with a namespace prefix, discards it and converts the short name into a legal Java field identifier (in "camelCase"). Caches the resulting bi-directional mapping in this Metadata.

Parameters:

nameToken - the XML name token.

Returns:

the Java field identifier.

toNameToken

public java.lang.String toNameToken(java.lang.String javaName)

Converts a Java class or field identifer back into an XML name token. Uses the cached inverse mapping to recover the original name token, complete with any namespace prefix. If no inverse mappings exist, returns a field-name unchanged, and attempts to convert a class-name by stripping the Java package name from the front of the full class name. If the Java package was bound to an XML namespace, retrieves this and prepends the XML namespace prefix to the returned name token. If no namespaces were ever bound, returns the short class-name after stripping off its package-name.

Parameters:

javaName - a Java class or field identifier.

Returns:

an XML name token, with optional namespace prefix.

getNamespacePrefix

private java.lang.String getNamespacePrefix(java.lang.String packageID)

Returns the short XML namespace prefix used to qualify XML elements representing objects from the given Java package. If a short XML namespace identifier was bound to the named Java package, returns the prefix part of that identifier. This method is used when converting Java class-names back to XML element-names.

Parameters:

packageID - the Java package name.

Returns:

the prefix, possibly empty, or null, if the package was not associated with any namespace.

addDomain

public void addDomain(java.lang.String domain)

Adds a DNS domain name to the set of recognised domain names. A DNS domain name is of the form: "host.domain.org" (or whatever). Java packages must all belong to a domain, so there must be at least one recognised domain name. Reversing the domain name yields the form: "org.domain.host" which is the start of one (or more) Java package names. The domain name is stored against this package prefix in a map. The package prefix is later used to retrieve the associated domain name, when generating a default namespace URI, in which part of the Java package name is interpreted as a domain name, and part is interpreted as a project directory tree.

Parameters:

domain - a DNS domain name.

bindNamespace

public void bindNamespace(java.lang.String namespace,
                          java.lang.String packageName)
                   throws SyntaxError

Associates a short XML namespace identifier with a Java package name in the namespace-to-package bindings. The namespace identifier is either "xmlns" for the default namespace, or of the form "xmlns:abc" for any declared namespace, where "abc" is the prefix used to identify XML elements in that namespace. Package names are given in the standard Java format "org.domain.host.project". This binding is used to generate an XML processing instruction mapping XML elements in the namespace to Java classes from the associated package. A default full namespace URI is also synthesised for the namespace, and is stored against the short identifier and stored in this Metadata's properties.

Parameters:

namespace - the XML namespace identifier.

packageName - the Java package name.

Throws:

SyntaxError

createNamespaceURI

private java.lang.String createNamespaceURI(java.lang.String namespace)

Creates an XML namespace URI for a short XML namespace identifier. The short XML namespace identifier is "xmlns" for a default namespace or "xmlns:abc" for a namespace with a prefix. This method creates a full URI for the namespace, by retrieving the Java package name bound to the identifier, and comparing this with registered domain names. A created URI of the form: "http://host.domain.org/project" corresponds to a Java package name: "org.domain.host.project". The created URI is stored against the namespace identifier in this Medatada's property map.

Parameters:

namespace - a short XML namespace identifier.

Returns:

a full XML namespace URI, created from the package name.

checkNamespaceID

private void checkNamespaceID(java.lang.String namespace)
                       throws SyntaxError

Validates the syntax of a short XML namespace identifier. Checks that the namespace identifier begins with "xmlns:" or is "xmlns".

Parameters:

namespace - a namespace short name.

Throws:

SyntaxError - if the short name is not valid.

checkDomainName

private void checkDomainName(java.lang.String domainName)
                      throws SyntaxError

Validates the syntax of a domain name or Java package name. Checks that the domain or package name consists of identifiers in lower case separated by dots.

Parameters:

domainName - a DNS domain name or Java package name.

Throws:

SyntaxError - if the domain or package name is not valid.

getNamespaces

public java.util.Set<java.lang.String> getNamespaces()

Returns the set of short XML namespace identifiers that were mapped to Java packages in the namespace-to-package bindings. Short namespace identifiers are of the form "xmlns" for the default namespace, or "xmlns:abc" for any declared namespace, where "abc" is the prefix identifying XML elements in this namespace.

Returns:

a set of short XML namespace identifiers.

toJavaPackage

public java.lang.String toJavaPackage(java.lang.String namespace)

Returns the name of the Java package associated with a given short XML namespace identifier in the namespace-to-package bindings. The namespace identifier is either "xmlns" for the default namespace, or of the form "xmlns:abc" for any declared namespace, where "abc" is the prefix identifying XML elements in this namespace. Java package names are returned in the standard Java format "org.domain.project".

Parameters:

namespace - the short XML namespace identifier.

Returns:

the corresponding Java package name.

toNamespaceURI

public java.lang.String toNamespaceURI(java.lang.String namespace)

Returns the full XML namespace URI associated with a given short XML namespace identifier in the Metadata properties. The XML namespace identifier is either "xmlns" for the default namespace, or of the form "xmlns:abc" for any declared namespace, where "abc" is the prefix identifying XML elements in this namespace. The returned namespace URI is a unique URI denoting an XML namespace, typically a URL web address.

Parameters:

namespace - the short XML namespace identifier.

Returns:

a unique full XML namespace URI.

processEntities

public void processEntities(Lexicon lexicon,
                            java.lang.String encoding)
                     throws java.io.IOException,
                            SyntaxError

Processes the external and internal grammar subsets in order to find any extra entity definitions. This Metadata stores links to both the external and internal grammar subsets in its properties. It will use one or two DTDReaders to process these DTDs, but will only add extra entity definitions to the lexicon. It cannot make use of the compiled grammar, since this can only be applied to check DOM-trees.

Parameters:

lexicon - the Lexicon from an ASTReader or ASTBuilder.

encoding - the expected character encoding, typically "UTF-8".

Throws:

java.io.IOException - if the DTDReader reader fails.

SyntaxError - if the DTD syntax is faulty.