V
- the type of the possible values for this attribute.@User public abstract class TypedAttribute<V> extends TypedNode<TypedExtension>
Most fields and methods of this class are not for user purpose. Generated subclasses define specialized public APIs. See the respective generated Javadocs for more precise information.
The encoding of the attribute declarations is as follows:cons val setValue(null) [!ATTLIST el default optional fixed absent clearValue() att1 CDATA "xy" "xy" true false "xy" SyntExc "xy" unspec att2 CDATA "xy" #FIXED "xy" true true "xy" SyntExc -- att3 CDATA #IMPLIED null true false null null=absent null=absent att4 CDATA #REQUIRED null false false MissingExc SyntExc Unsupported ]
When creating an element programmatically, the generated constructor code
calls a generated method initAttrs()
, which can be overridden. It
MUST be overridden if there are required attributes, which must be set there.
The idiom is
Element_X makeElement (String param_name) throws TdomAttributeSyntaxException { return new Element_X (content){ public void initAttrs() throws TdomAttributeSyntaxException{ //warning: using the identifier "name" instead of "param_name" would be //shadowed by "Element.name" getAttr_name().setValue(param_name); }} }A variant is
return new Element_X (safeValues, content){ public void initAttrsSafe(){ getAttr_name().setValue(param_name); }} }No
TdomAttributeSyntaxException
s can leave initAttrsSafe(), and the
alternative constructor thus does not throw them.
TypedAttribute.SafeValues
in the constructor invocation,
only method initAttrsSafe()
of the generated code is called. Otherwise
also initAttrs()
. This dependency cannot be checked.Modifier and Type | Class and Description |
---|---|
static class |
TypedAttribute.__PreAtts
Auxiliary class to signal in a type signature of a constructor that it is
called locally by another constructor which will handle attributes afterwards.
|
static class |
TypedAttribute.SafeValues
Auxiliary class to signal in a type signature that no
TdomAttributeSyntaxException s
can be thrown. |
TypedNode.ParseListener<E extends TypedElement<?,?>>
Modifier and Type | Field and Description |
---|---|
static TypedAttribute.__PreAtts |
__preAtts
Auxiliary constant to signal in a type signature of a constructor that it is
called locally by another constructor which will handle attributes afterwards.
|
static Attributes |
emptyAttributes
Auxiliary object for generating SAX start element events which do not involve attributes.
|
protected boolean |
mutable
A flag indicating whether the value of this attribute can be set after initialization.
|
static TypedAttribute.SafeValues |
safeValues
Auxiliary constant to signal in a type signature that no
TdomAttributeSyntaxException s can be thrown. |
protected boolean |
specified
A flag indicating whether the value of this attribute has been initialized
to an explicit value and not to the default.
|
protected V |
value
The value of this attribute, including
null for "absent". |
Modifier | Constructor and Description |
---|---|
protected |
TypedAttribute()
Constructs the instance which represents the default value.
|
protected |
TypedAttribute(TypedAttribute.SafeValues flag)
Constructor which does nothing.
|
protected |
TypedAttribute(V value)
Construct a new instance with a defined value during model construction.
|
Modifier and Type | Method and Description |
---|---|
static <W> void |
assertSetAttrValid(TypedAttribute<W> attr,
W value)
Wrapper for an attribute set method invocation when the author knows that a valid
value is provided, to replace a checked exception.
|
abstract void |
checkRequired()
The overriding method throws the exception if this attribute is required but missing
when initializing the tdom instance.
|
protected abstract void |
checkValue(V v)
Check routine for the validity of the attributes' intended value.
|
protected void |
clearValue()
Sets the value to the default, as defined in the DTD, and clear the "specified" flag.
|
protected static @Opt String |
find(Attributes attrs,
NamespaceName name)
Extract the string value for this attribute from a SAX input data structure.
|
protected static String |
find(Element element,
NamespaceName name)
Finds the value text for an attribute in a given XML DOM
element.
|
protected abstract V |
getDefaultValue()
Returns the default value defined in the DTD.
|
String |
getLocalName()
Returns the local part of the
NamespaceName . |
abstract NamespaceName |
getNamespaceName()
Returns the namespace name of the XML attribute.
|
String |
getNamespaceURI()
Returns the URI part of the namespace name.
|
String |
getStringValue()
Returns the current value of this attribute as it would be contained literally
in a possible XML text representation.
|
abstract String |
getStringValue(V v)
Returns the textual representation of a possible attribute value (not null),
as it would be contained literally in a possible XML text representation.
|
String |
getTagName()
Returns the qualified name of the attribute.
|
abstract String |
getTypeString()
The definition text for the "type" of the attribute in the original DTD.
|
V |
getValue()
Returns the current value of this attribute.
|
abstract boolean |
isFixed()
Returns whether the attribute is declared as "
#FIXED " in the DTD. |
abstract boolean |
isOptional()
Returns whether the attribute is declared as "
#IMPLIED " in the DTD. |
boolean |
isRequired()
Returns whether the attribute is declared as "
#REQUIRED " in the DTD. |
boolean |
isSpecified()
Checks whether this attribute should be included in an XML
representation of the containing element.
|
protected void |
makeUnspecified()
Only required when creating the prototype.
|
void |
put(AttributesImpl attributes,
String type)
Store this attribute into a SAX attributes implementation.
|
void |
setValue(V value)
Set the value of this attribute.
|
asBigDecimal, asBigDecimal, asBigDecimal, asBigDecimal, asBigInteger, asBigInteger, asBigInteger, asBigInteger, asBoolean, asBoolean, asDouble, asDouble, asDouble, asDouble, asFloat, asFloat, asFloat, asFloat, asHexInt, asHexInt, asHexInt, asHexInt, asInt, asInt, asInt, asInt, asLong, asLong, asLong, asLong, asTrimmedString, asTrimmedString, asTrimmedString, asTrimmedString, checkPlus, checkPlus, checkStar, checkStar, checkStrict, encode, encode, encodeOptional, encodePlus, encodePlus, encodeStar, encodeStar, extractEthereals, getLocation, getPCData, setLocation, setLocation, setLocation
public static final TypedAttribute.SafeValues safeValues
TdomAttributeSyntaxException
s can be thrown.public static final TypedAttribute.__PreAtts __preAtts
@Opt protected V value
null
for "absent".
Values are only permitted to be absent for attributes that
are declared with default value #IMPLIED
in the DTD.
Such attributes are omitted in XML text, DOM and SAX representations.protected boolean specified
#setValue(V)
.protected boolean mutable
setValue(V)
public static final Attributes emptyAttributes
protected TypedAttribute()
TdomAttributeSyntaxException
, because the
default value has been checked on source code generation.
This constructor is called first when initializing the generated Attr_[XY] class,
and its result is stored in the generated field "unspecified".
Then later, when the user invokes a "getAttr()" for a particular element for the
first time.
In case of a syntactically constrained attribute and #REQUIRED,
the default value is null and the construction result does
not represent a valid XML attribute. But if this instance does
appear in a model element object, after its creation, this fact will
lead to a TdomAttributeMissingException
.
ATTENTION the sequential order of the final static fields of the
generated class is critical: the field defaultValue
must be defined when this constructor
is called, which is used to create the value for the static field unspecified
(both fields only visible in generated code).
RuntimeException
- "class file corrupted", if the default value checked
during the tdom run is not longer a valid value.protected TypedAttribute(TypedAttribute.SafeValues flag)
TdomAttributeSyntaxException
-s
can never happen.protected TypedAttribute(@Opt V value) throws TdomAttributeSyntaxException
value
- the attribute value, or null
for "absent" in case of #IMPLIED.NullPointerException
- if name == null
.TdomAttributeSyntaxException
- iff the value does not meet the syntax criteria
of the DTD's declaration.public abstract String getTypeString()
protected abstract void checkValue(@Opt V v) throws TdomAttributeSyntaxException
#set_value(V)
method.
The value null
means "absent" for #IMPLIED
attributes and passes the test.v
- the value to test; maybe null.TdomAttributeSyntaxException
- iff the value does not match the type of the
XML attribute, including a forbidden Null.protected final void makeUnspecified()
@User public final String getTagName()
@User public final String getNamespaceURI()
NamespaceName
, or the empty string if namespaces are disabled.@User public final String getLocalName()
NamespaceName
.NamespaceName
.@User public abstract boolean isFixed()
#FIXED
" in the DTD.
Will be overridden by the generated code.#FIXED
" in the DTD.@User public abstract boolean isOptional()
#IMPLIED
" in the DTD.
Will be overridden by the generated code.#IMPLIED
" in the DTD.@User public final boolean isRequired()
#REQUIRED
" in the DTD.#REQUIRED
" in the DTD.@User @Opt public final V getValue()
null
if
this attribute is declared IMPLIED
and no value is
present.protected static String find(Element element, NamespaceName name)
element
- the element to search.name
- the namespace name of the attribute to find.UnsupportedOperationException
- if the attribute name
requires namespaces, but the implementation of the XML DOM
element does not support that feature.@Opt protected static @Opt String find(Attributes attrs, NamespaceName name)
org.xml.sax.Attributes.getValue(String,String)
for namespace URI and
local name. If no success, than tries
org.xml.sax.Attributes.getValue(String)
for the "qname".@User public void put(AttributesImpl attributes, String type)
type
- a "type indication" as it appears in a DTD. FIXME WARUM HIER EXPLIZIT??@User public final boolean isSpecified()
XML text DOM, and SAX representations may
omit attributes that have the declared default value, and
must omit attributes that are declared #IMPLIED
and have no value.
We let out all attributes which have neither been specified on model construction
nor set by the user afterwards.
(FIXME the name could better be "specifiedAndNotAbsent".
true
iff this attribute has been explicitly
initialized, and not set to null
.protected abstract V getDefaultValue()
public abstract NamespaceName getNamespaceName()
public abstract void checkRequired() throws TdomAttributeMissingException
TdomAttributeMissingException
@User public void setValue(@Opt V value) throws TdomAttributeSyntaxException
getAttr_XXX()
". The instance returned by
a call to "readAttr_XXX()
" is possibly the shared prototype,
which will throw an exception when trying to set the value.value
- maybe null, which sets the attribute to "not specified
when initializing the document", if it is declared #IMPLIED.UnsupportedOperationException
- if value is read only (= the attribute object
is the shared prototype)TdomAttributeSyntaxException
- if value==null is not permitted since
Attribute in DTD is declared as #REQUIRED
, or if the type (like "IDREFS")
is not met.TdomAttributeFixedException
- if a fixed value is missed.@User protected void clearValue()
setValue(V)
, this method
does noting.
Afterwards this attribute will not be included when writing out the model. This cannot
be achieved by just setting it to its the default value.
(The attribute is meant to be no longer be visited by a Visitor in "validating mode",
but this is not yet implemented.)
When the attribute is #IMPLIED, the default value is "absent", represnted as null.
UnsupportedOperationException
- when the attribute is #REQUIRED.
A #REQUIRED Attribute does not have a default value.@User public String getStringValue()
@User public abstract String getStringValue(V v)
@User public static <W> void assertSetAttrValid(TypedAttribute<W> attr, @Opt W value) throws AssertionError
TdomAttributeSyntaxException
in the middle of a deep nested constructor invocation, which often arises
in functional bottom-up programming style. Typical example:
new Element_a (... , assertAttrsComplete(()-> new Element_b(){ initAttrs(){ assertSetAttrValid(getAttr_x(), "y"); }}), ...)
Attributes which are #IMPLIED
and of CDataAttribute
or
of EnumerationAttribute
have an overridden setValue(V)
method which
never
throws a TdomAttributeSyntaxException
. and thus cannot be parameter to this method.
(The Java compiler will reject with an "...is never thrown..." error.)
attr
- the Attribute to set the value.value
- the value to check and assign to the attributeAssertionError
- if a TdomAttributeSyntaxException
is caughtsee also the complete user documentation .