Package eu.bandm.tools.tdom.runtime

Class TypedAttribute<V>

java.lang.Object
eu.bandm.tools.tdom.runtime.TypedNode<TypedExtension>
eu.bandm.tools.tdom.runtime.TypedAttribute<V>
Type Parameters:
V - the type of the possible values for this attribute.
Direct Known Subclasses:
CDataAttribute, EnumerationAttribute, NmTokenAttribute, NmTokensAttribute, SelectedIntegersAttribute
public abstract class TypedAttribute<V> extends TypedNode<TypedExtension>
Common base class for all attributes from some DTD.

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 TdomAttributeSyntaxExceptions can leave initAttrsSafe(), and the alternative constructor thus does not throw them.
Warning: When including TypedAttribute.SafeValues in the constructor invocation, only method initAttrsSafe() of the generated code is called. Otherwise also initAttrs(). This dependency cannot be checked.

  • Field Details

    • safeValues

      public static final TypedAttribute.SafeValues safeValues
      Auxiliary constant to signal in a type signature that no TdomAttributeSyntaxExceptions can be thrown.

    • __preAtts

      public static final 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. INTERNAL USE ONLY.

    • value

      @Opt protected V value
      The value of this attribute, including 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.

    • specified

      protected boolean specified
      A flag indicating whether the value of this attribute has been initialized to an explicit value and not to the default. Is false only for the prototype object, which is created on class loading and serves as default if the attribute is not present in the model construction phase, and not altered by the user by calling setValue(V).

    • mutable

      protected boolean mutable
      A flag indicating whether the value of this attribute can be set after initialization. Will be set to false in the prototype.
      See Also:

    • emptyAttributes

      public static final Attributes emptyAttributes
      Auxiliary object for generating SAX start element events which do not involve attributes.
      (Is also used by code outside of tdom.)

  • Constructor Details

    • TypedAttribute

      protected TypedAttribute()
      Constructs the instance which represents the default value. Does never throw a 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).

      Throws:
      RuntimeException - "class file corrupted", if the default value checked during the tdom run is not longer a valid value.

    • TypedAttribute

      protected TypedAttribute(TypedAttribute.SafeValues flag)
      Constructor which does nothing. Can only be called from trusted constructors in subclasses which set value and specified flag directly, without any test, because TdomAttributeSyntaxException-s can never happen.

    • TypedAttribute

      protected TypedAttribute(@Opt V value) throws TdomAttributeSyntaxException
      Construct a new instance with a defined value during model construction. (I.e. read from an XML text, or by user's explicit constructor invocation.) This code is called from the generated code. (The intermediate constructors of the subtypes are only pro forma.)
      Parameters:
      value - the attribute value, or null for "absent" in case of #IMPLIED.
      Throws:
      NullPointerException - if name == null.
      TdomAttributeSyntaxException - iff the value does not meet the syntax criteria of the DTD's declaration.

  • Method Details

    • getTypeString

      public abstract String getTypeString()
      The definition text for the "type" of the attribute in the original DTD.

    • checkValue

      protected abstract void checkValue(@Opt V v) throws TdomAttributeSyntaxException
      Check routine for the validity of the attributes' intended value. Is a call-back, implemented by the sub-classes. Is called only here, by two constructors and the setValue(V) method. The value null means "absent" for #IMPLIED attributes and passes the test.
      Parameters:
      v - the value to test; maybe null.
      Throws:
      TdomAttributeSyntaxException - iff the value does not match the type of the XML attribute, including a forbidden Null.

    • makeUnspecified

      protected final void makeUnspecified()
      Only required when creating the prototype. Is only called by the generated code, when the shared fixed default instance of this attribute is created on class loading.

    • getTagName

      public final String getTagName()
      Returns the qualified name of the attribute. This is a sequence of the the prefix which has been used when constructing the tdom instance and the local name. They are joined by the usual colon character iff the prefix is non-empty.
      FIXME WOFUER BENÖTIGT?? ist der prefix nicht irrelevant bei namespaces?
      Returns:
      the qualified name of the attribute, i.e. the local name and

    • getNamespaceURI

      public final String getNamespaceURI()
      Returns the URI part of the namespace name.
      Returns:
      the URI part of the NamespaceName, or the empty string if namespaces are disabled.

    • getLocalName

      public final String getLocalName()
      Returns the local part of the NamespaceName.
      Returns:
      the local part of the NamespaceName.

    • isFixed

      public abstract boolean isFixed()
      Returns whether the attribute is declared as "#FIXED" in the DTD. Will be overridden by the generated code.
      Returns:
      whether the attribute is declared as "#FIXED" in the DTD.

    • isOptional

      public abstract boolean isOptional()
      Returns whether the attribute is declared as "#IMPLIED" in the DTD. Will be overridden by the generated code.
      Returns:
      whether the attribute is declared as "#IMPLIED" in the DTD.

    • isRequired

      public final boolean isRequired()
      Returns whether the attribute is declared as "#REQUIRED" in the DTD.
      Returns:
      whether the attribute is declared as "#REQUIRED" in the DTD.

    • getValue

      @Opt public final V getValue()
      Returns the current value of this attribute.
      Returns:
      the current value of this attribute, or null if this attribute is declared IMPLIED and no value is present.

    • find

      protected static String find(Element element, NamespaceName name)
      Finds the value text for an attribute in a given XML DOM element.
      Parameters:
      element - the element to search.
      name - the namespace name of the attribute to find.
      Returns:
      the value text for the named attribute of the given element, or the empty string if the attribute is omitted and has no default value.
      Throws:
      UnsupportedOperationException - if the attribute name requires namespaces, but the implementation of the XML DOM element does not support that feature.

    • find

      @Opt protected static @Opt String find(Attributes attrs, NamespaceName name)
      Extract the string value for this attribute from a SAX input data structure. Tries TWO methods in this data structure: first Attributes.getValue(String,String) for namespace URI and local name. If no success, than tries Attributes.getValue(String) for the "qname".
      Returns:
      null if nothing is found.

    • put

      public void put(AttributesImpl attributes, String type)
      Store this attribute into a SAX attributes implementation.
      Parameters:
      type - a "type indication" as it appears in a DTD. FIXME WARUM HIER EXPLIZIT??

    • isSpecified

      public final boolean isSpecified()
      Checks whether this attribute should be included in an XML representation of the containing element.

      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".

      Returns:
      true iff this attribute has been explicitly initialized, and not set to null.

    • getDefaultValue

      protected abstract V getDefaultValue()
      Returns the default value defined in the DTD.
      Returns:
      the default value defined in the DTD.

    • getNamespaceName

      public abstract NamespaceName getNamespaceName()
      Returns the namespace name of the XML attribute.
      Returns:
      the namespace name of the XML attribute.

    • checkRequired

      public abstract void checkRequired() throws TdomAttributeMissingException
      The overriding method throws the exception if this attribute is required but missing when initializing the tdom instance.
      Throws:
      TdomAttributeMissingException

    • setValue

      public void setValue(@Opt V value) throws TdomAttributeSyntaxException
      Set the value of this attribute. This method is only guaranteed to succeed if this instance has been returned by the generated method "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.
      Parameters:
      value - maybe null, which sets the attribute to "not specified when initializing the document", if it is declared #IMPLIED.
      Throws:
      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.

    • clearValue

      protected void clearValue()
      Sets the value to the default, as defined in the DTD, and clear the "specified" flag. Reading and re-writing the same value will set the specified mark again.
      When this attribute has never been set by 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.

      Throws:
      UnsupportedOperationException - when the attribute is #REQUIRED. A #REQUIRED Attribute does not have a default value.

    • getStringValue

      public String getStringValue()
      Returns the current value of this attribute as it would be contained literally in a possible XML text representation. The value ==null means "absent", which is allowed with an #IMPLIED attribute, and returns the empty string.
      Returns:
      (never null) the current value of this attribute as it would be contained literally in a possible XML text representation.

    • getStringValue

      public 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. Since the textual representation of a String is the string itself, this method is relevant for enumeration types only (Later: also for "entity" types, but these are not yet supported.)
      Returns:
      (never null) the textual representation of this attribute value, as it would be contained literally in a possible XML text representation.

    • assertSetAttrValid

      public static <W> void assertSetAttrValid(TypedAttribute<W> attr, @Opt W value) throws AssertionError
      Wrapper for an attribute set method invocation when the author knows that a valid value is provided, to replace a checked exception. The typical usage pattern is to catch 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.)

      Parameters:
      attr - the Attribute to set the value.
      value - the value to check and assign to the attribute
      Throws:
      AssertionError - if a TdomAttributeSyntaxException is caught

    • assertSetAttrValid

      public static void assertSetAttrValid(SelectedIntegersAttribute attr, int value) throws AssertionError
      Throws:
      AssertionError