Interface MetaBean

  • All Known Subinterfaces:
    DynamicMetaBean, TypedMetaBean<T>
    All Known Implementing Classes:
    BasicMetaBean, DirectMetaBean, LightMetaBean, MinimalMetaBean, ReflectiveMetaBean

    public interface MetaBean
    A meta-bean, defining those aspects of a bean which are not specific to a particular instance, such as the type and set of meta-properties.

    This interface can be thought of as the equivalent of Class but for beans. In most cases the meta-bean will be code generated and the concrete class will have additional methods.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default <A extends java.lang.annotation.Annotation>
      A
      annotation​(java.lang.Class<A> annotationClass)
      Gets an annotation from the bean.
      default java.util.List<java.lang.annotation.Annotation> annotations()
      Gets the annotations associated with this bean.
      default java.lang.String beanName()
      Gets the bean name, which is normally the fully qualified class name of the bean.
      java.lang.Class<? extends Bean> beanType()
      Get the type of the bean, represented as a Class.
      BeanBuilder<? extends Bean> builder()
      Creates a bean builder that can be used to create an instance of this bean.
      boolean isBuildable()
      Checks whether this bean is buildable or not.
      default <R> MetaProperty<R> metaProperty​(java.lang.String propertyName)
      Gets a meta-property by name.
      default int metaPropertyCount()
      Counts the number of properties.
      default boolean metaPropertyExists​(java.lang.String propertyName)
      Checks if a property exists.
      default java.lang.Iterable<MetaProperty<?>> metaPropertyIterable()
      Gets an iterator of meta-properties.
      java.util.Map<java.lang.String,​MetaProperty<?>> metaPropertyMap()
      Gets the map of meta-properties, keyed by property name.
      static MetaBean of​(java.lang.Class<?> cls)
      Obtains a meta-bean from a Class.
      static void register​(MetaBean metaBean)
      Registers a meta-bean.
    • Method Detail

      • of

        static MetaBean of​(java.lang.Class<?> cls)
        Obtains a meta-bean from a Class.

        This will return a meta-bean if it has been registered, or if the class implements DynamicBean and has a no-args constructor. Note that the common case where the meta-bean is registered by a static initializer is handled.

        Parameters:
        cls - the class to get the meta-bean for, not null
        Returns:
        the meta-bean associated with the class, not null
        Throws:
        java.lang.IllegalArgumentException - if unable to obtain the meta-bean
      • register

        static void register​(MetaBean metaBean)
        Registers a meta-bean.

        This should be done for all beans in a static factory where possible. If the meta-bean is dynamic, this method should not be called.

        Parameters:
        metaBean - the meta-bean, not null
        Throws:
        java.lang.IllegalArgumentException - if unable to register
      • isBuildable

        boolean isBuildable()
        Checks whether this bean is buildable or not.

        A buildable bean can be constructed using builder(). If this method returns true then builder() must return a valid builder. If this method returns false then builder() must throw UnsupportedOperationException.

        Returns:
        true if this bean is buildable
      • builder

        BeanBuilder<? extends Bean> builder()
        Creates a bean builder that can be used to create an instance of this bean.

        The builder is used in two main ways. The first is to allow immutable beans to be constructed. The second is to enable automated tools like serialization/deserialization.

        The builder can be thought of as a Map of MetaProperty to value. Note that the implementation is not necessarily an actual map.

        Returns:
        the bean builder, not null
        Throws:
        java.lang.UnsupportedOperationException - if the bean cannot be created
      • beanName

        default java.lang.String beanName()
        Gets the bean name, which is normally the fully qualified class name of the bean.

        This is primarily used for human-readable output.

        Returns:
        the name of the bean, not empty
      • beanType

        java.lang.Class<? extends Bean> beanType()
        Get the type of the bean, represented as a Class.

        A MetaBean can be thought of as the equivalent of Class but for beans. This method allows the actual Class instance of the bean to be obtained.

        Returns:
        the type of the bean, not null
      • metaPropertyCount

        default int metaPropertyCount()
        Counts the number of properties.

        Each meta-bean manages a single bean with a known set of properties. This method returns the count of properties.

        Returns:
        the number of properties
      • metaPropertyExists

        default boolean metaPropertyExists​(java.lang.String propertyName)
        Checks if a property exists.

        Each meta-bean manages a single bean with a known set of properties. This method checks whether there is a property with the specified name.

        Parameters:
        propertyName - the property name to check, null returns false
        Returns:
        true if the property exists
      • metaProperty

        default <R> MetaProperty<R> metaProperty​(java.lang.String propertyName)
        Gets a meta-property by name.

        Each meta-bean manages a single bean with a known set of properties. This method returns the property with the specified name.

        The base interface throws an exception if the name is not recognised. By contrast, the DynamicMetaBean subinterface creates the property on demand.

        Type Parameters:
        R - the property type, optional, enabling auto-casting
        Parameters:
        propertyName - the property name to retrieve, not null
        Returns:
        the meta property, not null
        Throws:
        java.util.NoSuchElementException - if the property name is invalid
      • metaPropertyIterable

        default java.lang.Iterable<MetaProperty<?>> metaPropertyIterable()
        Gets an iterator of meta-properties.

        This method returns an Iterable, which is simpler than a Map. As a result, implementations may be able to optimise, and so this method should be preferred to metaPropertyMap() where a choice is possible.

        Returns:
        the unmodifiable map of meta property objects, not null
      • metaPropertyMap

        java.util.Map<java.lang.String,​MetaProperty<?>> metaPropertyMap()
        Gets the map of meta-properties, keyed by property name.

        Where possible, use metaPropertyIterable() instead as it typically has better performance.

        Returns:
        the unmodifiable map of meta property objects, not null
      • annotations

        default java.util.List<java.lang.annotation.Annotation> annotations()
        Gets the annotations associated with this bean.

        The annotations are queried from the bean. This is typically accomplished by querying the annotations of an underlying Class however any strategy is permitted.

        If the implementation has a mutable set of annotations, then the result of this method must stream over those annotations in existence when this method is called to avoid concurrency issues.

        The default implementation uses the annotations from beanType().

        Returns:
        the annotations, unmodifiable, not null
      • annotation

        default <A extends java.lang.annotation.Annotation> A annotation​(java.lang.Class<A> annotationClass)
        Gets an annotation from the bean.

        The annotations are queried from the bean. This is typically accomplished by querying the annotations of an underlying Class however any strategy is permitted.

        Type Parameters:
        A - the annotation type
        Parameters:
        annotationClass - the annotation class to find, not null
        Returns:
        the annotation, not null
        Throws:
        java.util.NoSuchElementException - if the annotation is not specified