Class 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 Detail

      • __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:
        setValue(V)
      • emptyAttributes

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

      • 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:
        java.lang.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:
        java.lang.NullPointerException - if name == null.
        TdomAttributeSyntaxException - iff the value does not meet the syntax criteria of the DTD's declaration.
    • Method Detail

      • getTypeString

        public abstract java.lang.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 #set_value(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 java.lang.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 java.lang.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 java.lang.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 java.lang.String find​(org.w3c.dom.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:
        java.lang.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 java.lang.String find​(org.xml.sax.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 {@link org.xml.sax.Attributes.getValue(String,String)} for namespace URI and local name. If no success, than tries {@link org.xml.sax.Attributes.getValue(String)} for the "qname".
        Returns:
        null if nothing is found.
      • put

        public void put​(org.xml.sax.helpers.AttributesImpl attributes,
                        java.lang.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.
      • 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:
        java.lang.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:
        java.lang.UnsupportedOperationException - when the attribute is #REQUIRED. A #REQUIRED Attribute does not have a default value.
      • getStringValue

        public java.lang.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 java.lang.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 java.lang.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:
        java.lang.AssertionError - if a TdomAttributeSyntaxException is caught