Module io.github.mmm.bean
Package io.github.mmm.bean

Interface ReadableBean

All Superinterfaces:
AttributeReadOnly, io.github.mmm.marshall.MarshallableObject, io.github.mmm.marshall.Marshaller<Object>, io.github.mmm.validation.Validatable
All Known Subinterfaces:
VirtualBean, WritableBean
All Known Implementing Classes:
AbstractBean, AbstractVirtualBean, AdvancedBean, Bean, DynamicBean
public interface ReadableBean extends io.github.mmm.validation.Validatable, io.github.mmm.marshall.MarshallableObject, AttributeReadOnly
Read interface of a Bean holding arbitrary properties. Unlike plain old Java Beans this offers a lot of advanced features:
  • Simple - no need to write boiler-plate code for implementation such as getters, setters, equals, or hashCode.
  • Generic - fast, easy and reliable introspection via iteration of all properties. No more greedy and slow reflection at runtime (after bootstrapping).
  • Dynamic - supports combination of Java's strong typing with dynamic beans. E.g. if read data from Database, XML, or JSON you can still map "undefined" properties in your Bean. This way a client can receive an object from a newer version of a database or service with added properties that will be kept in the object and send back when the Bean is written back.
  • ReadOnly-Support - create a read-only copy of your object to pass by reference without side-effects.
  • Powerful - WritableProperty supports listeners and bindings as well as generic type information.
  • Validation - build-in validation support.
  • Marshalling - build-in support to read and write the Bean from/to JSON, XML, or other formats. Implement custom datatypes as property and you will not need separate classes or configurations for mapping.
  • Portable - everything relies only on established Java standard mechanisms. No customization of build processes, IDEs, etc. needed. It just works with any build tool (maven, gradle, buildr, ant, etc.) and IDE (Eclipse, IntelliJ, NetBeans, etc.) without plugins and therefore will also work in the future whatever may come.

  • Field Details

  • Method Details

    • getProperty

      ReadableProperty<?> getProperty(String name)
      Parameters:
      name - the name of the requested property or a potential alias of the property.
      Returns:
      the requested WritableProperty or null if no such property exists.
      See Also:

    • getProperties

      Collection<? extends ReadableProperty<?>> getProperties()
      Returns:
      a Collection with all properties of this bean.

    • getPropertyCount

      int getPropertyCount()
      Returns:
      the number of properties of this ReadableBean.

    • getRequiredProperty

      default ReadableProperty<?> getRequiredProperty(String name)
      Parameters:
      name - the name of the requested property.
      Returns:
      the requested property.
      Throws:
      RuntimeException - if the requested property does not exist.

    • get

      default <V> V get(String name)
      Type Parameters:
      V - type of the property value.
      Parameters:
      name - the property name.
      Returns:
      the value of the property with the given name. Will be null if no such property exists or the property value is null.

    • getPropertyNameForAlias

      default String getPropertyNameForAlias(String alias)
      An alias is an alternative for a property name. It allows to support a property under a legacy name after it has been renamed as well as to use a technical name containing special characters (e.g. "@" or ".") for very specific cases.
      Parameters:
      alias - the alias name.
      Returns:
      the resolved property name or null if no such alias is defined.

    • getType

      BeanType getType()
      Returns:
      the BeanType reflecting this Bean.
      See Also:

    • isDynamic

      boolean isDynamic()
      Returns:
      true if this Bean is dynamic meaning that is not strictly typed but allows to dynamically add properties, false otherwise.
      See Also:

    • isPrototype

      boolean isPrototype()
      Returns:
      true if this Bean is a BeanClass, false otherwise (it is a regular instance).
      See Also:

    • isPolymorphic

      default boolean isPolymorphic()
      A Bean may be polymorphic to allow mappings to and from other representations without knowing the exact type. So assuming a service accepts or returns a Bean of a specific type that has sub-types. If that type is declared as polymorphic then it is possible to unarshall the Bean of the exact sub-type back from its serialized data.
      By default a Bean is not polymorphic. Once you declare your custom Bean as polymorphic by overriding this method returning true, you may not this method it again. Hence, if you override this method in a class, you should declare it as final.
      Returns:
      true if this Bean is polymorphic meaning it represents an entire hierarchy of Bean types, false otherwise.

    • validate

      default io.github.mmm.validation.ValidationResult validate()
      Specified by:
      validate in interface io.github.mmm.validation.Validatable

    • isEqualTo

      default boolean isEqualTo(ReadableBean other)
      A Bean implementation shall not override Object.equals(Object) and Object.hashCode() for efficient usage in Collections and Maps. Hence the regular equals method will just check for object identity. For a logical equals check you may use this method. Be aware that is may be expensive as it recursively traverses into all properties that may again contain a ReadableBean.
      Parameters:
      other - the ReadableBean to compare with.
      Returns:
      true if this ReadableBean is logically equal to the given ReadableBean, that is it has the same type and all properties are equal, false otherwise.

    • copy

      WritableBean copy(boolean readOnly)
      Parameters:
      readOnly - - true if the copy shall be read-only.
      Returns:
      a copy of this WritableBean that has the same values for all properties.

    • newInstance

      WritableBean newInstance()
      Returns:
      a new instance of this WritableBean.

    • mapPropertyIds

      default void mapPropertyIds(PropertyIdCollector mapping)
      Defines how the properties of this ReadableBean are mapped to numeric IDs. This is only relevant in case you want to use binary protocols ProtoBuf/GRPC.
      Parameters:
      mapping - the PropertyIdCollector used to receive the mapping.

    • doEquals

      default boolean doEquals(ReadableBean other)
      Method to implement #equals(Object) directly in a bean interface as default method. For simplification it is only called if the object to compare to is not null and has the same type so you do not have to handle these cases in your custom implementation.
      ATTENTION: It is rather discouraged to override this method. Simply use isEqualTo(ReadableBean) instead of #equals(Object) when you want comparison by value (e.g. to check for duplicates).
      Parameters:
      other - the object to compare to. Will not be null and has the same type as this bean.
      Returns:
      true if this and the given ReadableBean are considered equals, false otherwise.
      See Also:

    • doToString

      default String doToString()
      Method to implement #toString() directly in a bean interface as default method.
      Returns:
      the string representation of this bean.

    • toString

      default void toString(StringBuilder sb)
      Parameters:
      sb - the StringBuilder where to append the details (the properties) of this Bean for #toString()-Representation.

    • newInstance

      static <B extends ReadableBean> B newInstance(B bean)
      Type Parameters:
      B - type of the WritableBean.
      Parameters:
      bean - the WritableBean to create a new instance of.
      Returns:
      the new instance.

    • copy

      static <B extends ReadableBean> B copy(B bean, boolean readOnly)
      Type Parameters:
      B - type of the WritableBean.
      Parameters:
      bean - the WritableBean to copy.
      readOnly - - true if the copy shall be read-only.
      Returns:
      the copy.

    • copyReadOnly

      static <B extends ReadableBean> B copyReadOnly(B bean)
      Type Parameters:
      B - type of the WritableBean.
      Parameters:
      bean - the WritableBean to copy.
      Returns:
      the read-only copy.