Package org.jboss.as.controller

Class AttributeDefinition

    • Method Detail

      • 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

      • isAllowNull

        @Deprecated
public boolean isAllowNull()
        Deprecated.
        use either isRequired() or isNillable() depending on which provides the desired information
        Inverse of isRequired().

        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 valid 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

      • isValidatingNull

        @Deprecated
public boolean isValidatingNull()
        Deprecated.
        this is no longer configurable, so this getter may be removed in a future major release.
        Gets whether the attribute definition is checking for undefined values. This will be true for attributes that are not isRequired() (although the validation is meaningless, since undefined is valid) and for required attributes that have alternatives.

        Validation by the AttributeDefinition of required attributes with alternatives is not possible, as the necessary context of the overall change being made is not available.

        Returns:
        true if validation will check undefined values.

      • 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

        @Deprecated
public EnumSet<AttributeAccess.Flag> getFlags()
        Deprecated.
        In the next release, the return type of this method will become simply Set and the returned object will be immutable, so any callers should update their code to reflect that
        Gets a set of any flags used to indicate special characteristics of the attribute
        Returns:
        the flags. Will not be null but may be empty.

      • getImmutableFlags

        @Deprecated
public Set<AttributeAccess.Flag> getImmutableFlags()
        Deprecated.
        for internal use only; will be dropped when the semantic of getFlags() is changed to return an immutable Set
        Provides an immutable variant of the set returned by getFlags().

      • 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

        @Deprecated
public void addCapabilityRequirements​(OperationContext context,
                                      org.jboss.dmr.ModelNode attributeValue)
        Deprecated.
        use @{link addCapabilityRequirements(OperationContext, Resource, ModelNode)} variant
        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
        attributeValue - the value of the attribute described by this object

      • 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 -
        attributeValue - the value of the attribute described by this object

      • removeCapabilityRequirements

        @Deprecated
public void removeCapabilityRequirements​(OperationContext context,
                                         org.jboss.dmr.ModelNode attributeValue)
        Deprecated.
        use removeCapabilityRequirements(OperationContext, Resource, ModelNode) variant
        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
        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:

      • 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

      • addAccessConstraints

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

      • 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