Package org.jboss.as.controller

Class AttributeDefinition

java.lang.Object
org.jboss.as.controller.AttributeDefinition
All Implemented Interfaces:
Feature
Direct Known Subclasses:
ListAttributeDefinition, MapAttributeDefinition, SimpleAttributeDefinition
public abstract class AttributeDefinition extends Object implements Feature
Defining characteristics of an attribute in a Resource or a parameter or reply value type field in an OperationDefinition, with utility methods for validation.
Author:
Brian Stansberry (c) 2011 Red Hat Inc.

  • Field Details

    • COMPLEX_TYPES

      protected static final Set<org.jboss.dmr.ModelType> COMPLEX_TYPES
      The ModelType types that reflect complex DMR structures -- LIST, OBJECT, PROPERTY}

  • Constructor Details

  • Method Details

    • getStability

      public Stability getStability()
      Description copied from interface: Feature
      Returns the stability level of this feature.
      Specified by:
      getStability in interface Feature
      Returns:
      a stability level

    • getName

      public String getName()
      The attribute's name in the management model.
      Returns:
      the name. Will not be null

    • getXmlName

      public String getXmlName()
      The attribute's name in the xml configuration. Not relevant for operation parameters and reply value types.
      Returns:
      the name. Will not be null, although it may not be relevant

    • getType

      public org.jboss.dmr.ModelType getType()
      The expected type of the ModelNode that holds the attribute data.
      Returns:
      the type. Will not be null

    • isRequired

      public boolean isRequired()
      Whether a ModelNode holding the value of this attribute can be ModelType.UNDEFINED when all other attributes in the same overall model that are alternatives of this attribute are undefined.

      In a valid model an attribute that is required must be undefined if any alternative is defined, so this method should not be used for checking if it is valid for the attribute ever to have an undefined value. Use isNillable() for that.

      Returns:
      true if an undefined ModelNode is invalid in the absence of alternatives; false if not

    • isNillable

      public boolean isNillable()
      Whether a ModelNode holding the value of this attribute can be ModelType.UNDEFINED in any situation. An attribute that ordinarily is required may still be undefined in a given model if an alternative attribute is defined.

      This is equivalent to !isRequired() || (getAlternatives() != null && getAlternatives().length > 0).

      Returns:
      true if an undefined ModelNode is valid; false if not

    • isNullSignificant

      public final boolean isNullSignificant()
      Gets whether an access control check is required to implicitly set an attribute to undefined in a resource "add" operation. "Implicitly" setting an attribute refers to not providing a value for it in the add operation, leaving the attribute in an undefined state. So, if a user attempts to add a resource but does not define some attributes, a write permission check will be performed for any attributes where this method returns true.

      Generally this is true if undefined is allowed and a default value exists, although some instances may have a different setting.

      Returns:
      true if an undefined value is significant

    • isAllowExpression

      public boolean isAllowExpression()
      Whether a ModelNode holding the value of this attribute can be ModelType.EXPRESSION.
      Returns:
      true if an expression ModelNode is valid; false if not

    • getDefaultValue

      public org.jboss.dmr.ModelNode getDefaultValue()
      Gets the default value to use for the attribute if a value was not provided.
      Returns:
      the default value, or null if no defined value was provided

    • getAttributeGroup

      public String getAttributeGroup()
      Gets the name of the attribute group with which this attribute is associated, if any.
      Returns:
      the name of the group, or null if the attribute is not associated with a group

    • getMeasurementUnit

      public MeasurementUnit getMeasurementUnit()
      The unit of measure in which an attribute with a numerical value is expressed.
      Returns:
      the measurement unit, or null if none is relevant

    • getCorrector

      public ParameterCorrector getCorrector()
      Gets the corrector used to correct values before checking that they comply with the attribute's definition.
      Returns:
      the corrector. May be null

    • getValidator

      public ParameterValidator getValidator()
      Gets the validator used to validate that values comply with the attribute's definition.
      Returns:
      the validator. Will not be null

    • getAlternatives

      public String[] getAlternatives()
      Gets the names of other attributes whose value must be undefined if this attribute's value is defined, and vice versa.
      Returns:
      the alternative attribute names, or null if there are no such attributes

    • getRequires

      public String[] getRequires()
      Gets the names of other attributes whose value must not be undefined if this attribute's value is defined.
      Returns:
      the required attribute names, or null if there are no such attributes

    • getFlags

      public Set<AttributeAccess.Flag> getFlags()
      Returns an immutable set of any flags used to indicate special characteristics of the attribute
      Returns:
      the flags. Will not be null but may be empty.

    • getAllowedValues

      public List<org.jboss.dmr.ModelNode> getAllowedValues()
      returns array with all allowed values
      Returns:
      allowed values

    • getArbitraryDescriptors

      public Map<String,org.jboss.dmr.ModelNode> getArbitraryDescriptors()

    • isMarshallable

      public boolean isMarshallable(org.jboss.dmr.ModelNode resourceModel)
      Gets whether the given resourceModel has a value for this attribute that should be marshalled to XML.

      This is the same as isMarshallable(resourceModel, true).

      Parameters:
      resourceModel - the model, a non-null node of ModelType.OBJECT.
      Returns:
      true if the given resourceModel has a defined value under this attribute's getName() () name}.

    • isMarshallable

      public boolean isMarshallable(org.jboss.dmr.ModelNode resourceModel, boolean marshallDefault)
      Gets whether the given resourceModel has a value for this attribute that should be marshalled to XML.
      Parameters:
      resourceModel - the model, a non-null node of ModelType.OBJECT.
      marshallDefault - true if the value should be marshalled even if it matches the default value
      Returns:
      true if the given resourceModel has a defined value under this attribute's getName() () name} and marshallDefault is true or that value differs from this attribute's default value.

    • validateOperation

      public org.jboss.dmr.ModelNode validateOperation(org.jboss.dmr.ModelNode operationObject) throws OperationFailedException
      Finds a value in the given operationObject whose key matches this attribute's name and validates it using this attribute's validator.
      Parameters:
      operationObject - model node of type ModelType.OBJECT, typically representing an operation request
      Returns:
      the value
      Throws:
      OperationFailedException - if the value is not valid

    • validateAndSet

      public final void validateAndSet(org.jboss.dmr.ModelNode operationObject, org.jboss.dmr.ModelNode model) throws OperationFailedException
      Finds a value in the given operationObject whose key matches this attribute's name, validates it using this attribute's validator, and, stores it under this attribute's name in the given model.
      Parameters:
      operationObject - model node of type ModelType.OBJECT, typically representing an operation request
      model - model node in which the value should be stored
      Throws:
      OperationFailedException - if the value is not valid

    • resolveModelAttribute

      public org.jboss.dmr.ModelNode resolveModelAttribute(OperationContext context, org.jboss.dmr.ModelNode model) throws OperationFailedException
      Finds a value in the given model whose key matches this attribute's name, uses the given context to resolve it and validates it using this attribute's validator. If the value is undefined and a default value is available, the default value is used.
      Parameters:
      context - the operation context
      model - model node of type ModelType.OBJECT, typically representing a model resource
      Returns:
      the resolved value, possibly the default value if the model does not have a defined value matching this attribute's name
      Throws:
      OperationFailedException - if the value is not valid

    • resolveModelAttribute

      public org.jboss.dmr.ModelNode resolveModelAttribute(ExpressionResolver resolver, org.jboss.dmr.ModelNode model) throws OperationFailedException
      Finds a value in the given model whose key matches this attribute's name, uses the given resolver to ExpressionResolver.resolveExpressions(org.jboss.dmr.ModelNode) resolve} it and validates it using this attribute's validator. If the value is undefined and a default value is available, the default value is used.
      Parameters:
      resolver - the expression resolver
      model - model node of type ModelType.OBJECT, typically representing a model resource
      Returns:
      the resolved value, possibly the default value if the model does not have a defined value matching this attribute's name
      Throws:
      OperationFailedException - if the value is not valid

    • resolveValue

      public org.jboss.dmr.ModelNode resolveValue(OperationContext context, org.jboss.dmr.ModelNode value) throws OperationFailedException
      Takes the given value, resolves it using the given context and validates it using this attribute's validator. If the value is undefined and a default value is available, the default value is used.
      Parameters:
      context - the context to use to resolve the value
      value - a node that is expected to be a valid value for an attribute defined by this definition
      Returns:
      the resolved value, possibly the default value if value is not defined
      Throws:
      OperationFailedException - if the value is not valid

    • resolveValue

      public org.jboss.dmr.ModelNode resolveValue(ExpressionResolver resolver, org.jboss.dmr.ModelNode value) throws OperationFailedException
      Takes the given value, resolves it using the given resolver and validates it using this attribute's validator. If the value is undefined and a default value is available, the default value is used.
      Parameters:
      resolver - the expression resolver
      value - a node that is expected to be a valid value for an attribute defined by this definition
      Returns:
      the resolved value, possibly the default value if value is not defined
      Throws:
      OperationFailedException - if the value is not valid

    • isAllowed

      public boolean isAllowed(org.jboss.dmr.ModelNode operationObject)
      Inverse of hasAlternative(org.jboss.dmr.ModelNode).
      Parameters:
      operationObject - an object ModelNode whose keys are attribute names.
      Returns:
      true if operationObject has no defined values for attributes configured as our alternatives

    • isRequired

      public boolean isRequired(org.jboss.dmr.ModelNode operationObject)
      Gets whether this attribute must be defined in the given operationObject
      Parameters:
      operationObject - an object ModelNode whose keys are attribute names.
      Returns:
      true if this attribute is required and the given operationObject does not have any defined attributes configured as alternatives to this attribute

    • hasAlternative

      public boolean hasAlternative(org.jboss.dmr.ModelNode operationObject)
      Gets whether this attribute has alternatives configured and the given operationObject has any of those alternatives defined.
      Parameters:
      operationObject - an object ModelNode whose keys are attribute names.
      Returns:
      true if operationObject has any defined values for attributes configured as our alternatives

    • marshallAsElement

      public void marshallAsElement(org.jboss.dmr.ModelNode resourceModel, XMLStreamWriter writer) throws XMLStreamException
      Marshalls the value from the given resourceModel as an xml element, if it is marshallable.
      Parameters:
      resourceModel - the model, a non-null node of ModelType.OBJECT.
      writer - stream writer to use for writing the attribute
      Throws:
      XMLStreamException - if thrown by writer

    • marshallAsElement

      public void marshallAsElement(org.jboss.dmr.ModelNode resourceModel, boolean marshallDefault, XMLStreamWriter writer) throws XMLStreamException
      Marshalls the value from the given resourceModel as an xml element, if it is marshallable.
      Parameters:
      resourceModel - the model, a non-null node of ModelType.OBJECT.
      marshallDefault - true if the value should be marshalled even if it matches the default value
      writer - stream writer to use for writing the attribute
      Throws:
      XMLStreamException - if thrown by writer

    • addResourceAttributeDescription

      public org.jboss.dmr.ModelNode addResourceAttributeDescription(ResourceBundle bundle, String prefix, org.jboss.dmr.ModelNode resourceDescription)
      Creates a returns a basic model node describing the attribute, after attaching it to the given overall resource description model node. The node describing the attribute is returned to make it easy to perform further modification.
      Parameters:
      bundle - resource bundle to use for text descriptions
      prefix - prefix to prepend to the attribute name key when looking up descriptions
      resourceDescription - the overall resource description
      Returns:
      the attribute description node

    • addResourceAttributeDescription

      public org.jboss.dmr.ModelNode addResourceAttributeDescription(org.jboss.dmr.ModelNode resourceDescription, ResourceDescriptionResolver resolver, Locale locale, ResourceBundle bundle)
      Creates a returns a basic model node describing the attribute, after attaching it to the given overall resource description model node. The node describing the attribute is returned to make it easy to perform further modification.
      Parameters:
      resourceDescription - the overall resource description
      resolver - provider of localized text descriptions
      locale - locale to pass to the resolver
      bundle - bundle to pass to the resolver
      Returns:
      the attribute description node

    • addOperationParameterDescription

      public org.jboss.dmr.ModelNode addOperationParameterDescription(ResourceBundle bundle, String prefix, org.jboss.dmr.ModelNode operationDescription)
      Creates a returns a basic model node describing a parameter that sets this attribute, after attaching it to the given overall operation description model node. The node describing the parameter is returned to make it easy to perform further modification.
      Parameters:
      bundle - resource bundle to use for text descriptions
      prefix - prefix to prepend to the attribute name key when looking up descriptions
      operationDescription - the overall resource description
      Returns:
      the attribute description node

    • addOperationParameterDescription

      public org.jboss.dmr.ModelNode addOperationParameterDescription(org.jboss.dmr.ModelNode resourceDescription, String operationName, ResourceDescriptionResolver resolver, Locale locale, ResourceBundle bundle)
      Creates a returns a basic model node describing a parameter that sets this attribute, after attaching it to the given overall operation description model node. The node describing the parameter is returned to make it easy to perform further modification.
      Parameters:
      resourceDescription - the overall resource description
      operationName - the operation name
      resolver - provider of localized text descriptions
      locale - locale to pass to the resolver
      bundle - bundle to pass to the resolver
      Returns:
      the attribute description node

    • addOperationReplyDescription

      public org.jboss.dmr.ModelNode addOperationReplyDescription(ResourceBundle bundle, String prefix, org.jboss.dmr.ModelNode operationDescription)
      Creates a returns a basic model node describing a parameter that sets this attribute, after attaching it to the given overall operation description model node. The node describing the parameter is returned to make it easy to perform further modification.
      Parameters:
      bundle - resource bundle to use for text descriptions
      prefix - prefix to prepend to the attribute name key when looking up descriptions
      operationDescription - the overall resource description
      Returns:
      the attribute description node

    • addOperationReplyDescription

      public org.jboss.dmr.ModelNode addOperationReplyDescription(org.jboss.dmr.ModelNode resourceDescription, String operationName, ResourceDescriptionResolver resolver, Locale locale, ResourceBundle bundle)
      Creates a returns a basic model node describing a parameter that sets this attribute, after attaching it to the given overall operation description model node. The node describing the parameter is returned to make it easy to perform further modification.
      Parameters:
      resourceDescription - the overall resource description
      operationName - the operation name
      resolver - provider of localized text descriptions
      locale - locale to pass to the resolver
      bundle - bundle to pass to the resolver
      Returns:
      the attribute description node

    • getAttributeTextDescription

      public String getAttributeTextDescription(ResourceBundle bundle, String prefix)
      Gets localized text from the given ResourceBundle for the attribute.
      Parameters:
      bundle - the resource bundle. Cannot be null
      prefix - a prefix to dot-prepend to the attribute name to form a key to resolve in the bundle
      Returns:
      the resolved text

    • getAttributeDeprecatedDescription

      public String getAttributeDeprecatedDescription(ResourceBundle bundle, String prefix)
      Gets localized deprecation text from the given ResourceBundle for the attribute.
      Parameters:
      bundle - the resource bundle. Cannot be null
      prefix - a prefix to dot-prepend to the attribute name to form a key to resolve in the bundle
      Returns:
      the resolved text

    • addDeprecatedInfo

      public org.jboss.dmr.ModelNode addDeprecatedInfo(org.jboss.dmr.ModelNode model)
      Adds attribute deprecation information, if relevant, to the given attribute description node
      Parameters:
      model - the attribute description
      Returns:
      the node added to model or null if no deprecation data was needed

    • getNoTextDescription

      public org.jboss.dmr.ModelNode getNoTextDescription(boolean forOperation)
      Gets descriptive metadata for this attribute, excluding free-from text description fields.
      Parameters:
      forOperation - true if the metadata is for an operation parameter or reply value type
      Returns:
      object node containing the descriptive metadata

    • addCapabilityRequirements

      public void addCapabilityRequirements(OperationContext context, Resource resource, org.jboss.dmr.ModelNode attributeValue)
      Based on the given attribute value, add capability requirements. If this definition is for an attribute whose value is or contains a reference to the name of some capability, this method should record the addition of a requirement for the capability.

      This is a no-op in this base class. Subclasses that support attribute types that can represent capability references should override this method.

      Parameters:
      context - the operation context
      resource - the resource on which requirements are gathered
      attributeValue - the value of the attribute described by this object

    • removeCapabilityRequirements

      public void removeCapabilityRequirements(OperationContext context, Resource resource, org.jboss.dmr.ModelNode attributeValue)
      Based on the given attribute value, remove capability requirements. If this definition is for an attribute whose value is or contains a reference to the name of some capability, this method should record the removal of a requirement for the capability.

      This is a no-op in this base class. Subclasses that support attribute types that can represent capability references should override this method.

      Parameters:
      context - the operation context
      resource - resource from which capability requirement is to be removed from, null is legal value in case that CapabilityReferenceRecorder doesn't require it.
      attributeValue - the value of the attribute described by this object

    • hasCapabilityRequirements

      public boolean hasCapabilityRequirements()
      Based on the given attribute value, tell if attribute has any capability requirements. If this definition is for an attribute whose value is or contains a reference to the name of some capability, this method will return true otherwise false.

      This is a no-op in this base class. Subclasses that support attribute types that can represent capability references should override this method.

      Returns:
      true if this definition is for an attribute whose value is or contains a reference to the name of some capability

    • getReferenceRecorder

      protected CapabilityReferenceRecorder getReferenceRecorder()

    • addAllowedValuesToDescription

      protected void addAllowedValuesToDescription(org.jboss.dmr.ModelNode result, ParameterValidator validator)
      Adds the allowed values. Override for attributes who should not use the allowed values.
      Parameters:
      result - the node to add the allowed values to
      validator - the validator to get the allowed values from

    • correctValue

      protected final org.jboss.dmr.ModelNode correctValue(org.jboss.dmr.ModelNode newValue, org.jboss.dmr.ModelNode oldValue)
      Corrects the value if the value corrector is not null. If the value corrector is null, the newValue parameter is returned.
      Parameters:
      newValue - the new value.
      oldValue - the old value.
      Returns:
      the corrected value or the newValue if the value corrector is null.

    • convertParameterExpressions

      protected org.jboss.dmr.ModelNode convertParameterExpressions(org.jboss.dmr.ModelNode parameter)
      Examine the given operation parameter value for any expression syntax, converting the relevant node to ModelType.EXPRESSION if such is supported.

      This implementation checks if expressions are allowed and if so, calls convertStringExpression(ModelNode) to convert a ModelType.STRING to a ModelType.EXPRESSION. No other conversions are performed. For use cases requiring more complex behavior, a subclass that overrides this method should be used.

      If expressions are supported this implementation also checks if the attribute type is one of the complex DMR types. If it is, an IllegalStateException is thrown, as this implementation cannot properly handle such a combination, and a subclass that overrides this method should be used.

      Parameters:
      parameter - the node to examine. Cannot not be null
      Returns:
      a node matching parameter but with expressions converted, or the original parameter if no conversion was performed. Will not return null
      Throws:
      IllegalStateException - if expressions are supported, but the attribute type is complex

    • convertStringExpression

      protected static org.jboss.dmr.ModelNode convertStringExpression(org.jboss.dmr.ModelNode node)
      Checks if the given node is of ModelType.STRING with a string value that includes expression syntax. If so returns a node of ModelType.EXPRESSION, else simply returns node unchanged
      Parameters:
      node - the node to examine. Will not be null
      Returns:
      the node with expressions converted, or the original node if no conversion was performed Cannot return null

    • getMarshaller

      public AttributeMarshaller getMarshaller()
      Returns:
      attribute marshaller that can be used to persist attribute to XML

    • isResourceOnly

      public boolean isResourceOnly()
      Show if attribute is resource only which means it wont be part of add operations but only present on resource
      Returns:
      true is attribute is resource only

    • isDeprecated

      public boolean isDeprecated()
      Returns:
      true if attribute is deprecated

    • getDeprecationData

      public DeprecationData getDeprecationData()
      return deprecation data if there is any
      Returns:
      DeprecationData

    • getAccessConstraints

      public List<AccessConstraintDefinition> getAccessConstraints()

    • addAccessConstraints

      protected void addAccessConstraints(org.jboss.dmr.ModelNode result, Locale locale)

    • getParser

      public AttributeParser getParser()

    • getUndefinedMetricValue

      public org.jboss.dmr.ModelNode getUndefinedMetricValue()
      Gets the undefined metric value to use for the attribute if a value cannot be provided.
      Returns:
      the undefined metric value, or null if no undefined metric value was provided

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object object)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object