EntityModel (Oracle - Berkeley DB Java API)
Date: 2020-06-01

Package com.sleepycat.persist.model

## Class EntityModel

- java.lang.Object
- - com.sleepycat.persist.model.EntityModel

- Direct Known Subclasses:
    `AnnotationModel`

      public abstract class EntityModel
      extends java.lang.Object

  The base class for classes that provide entity model metadata. An `EntityModel` defines entity classes, primary keys, secondary keys, and relationships between entities. For each entity class that is part of the model, a single `PrimaryIndex` object and zero or more `SecondaryIndex` objects may be accessed via an `EntityStore`.

  The built-in entity model, the `AnnotationModel`, is based on annotations that are added to entity classes and their key fields. Annotations are used in the examples in this package, and it is expected that annotations will normally be used; most readers should therefore skip to the `AnnotationModel` class. However, a custom entity model class may define its own metadata. This can be used to define entity classes and keys using mechanisms other than annotations.

  A concrete entity model class should extend this class and implement the `getClassMetadata(java.lang.String)`, `getEntityMetadata(java.lang.String)` and `getKnownClasses()` methods.

  This is an abstract class rather than an interface to allow adding capabilities to the model at a future date without causing incompatibilities. For example, a method may be added in the future for returning new information about the model and subclasses may override this method to return the new information. Any new methods will have default implementations that return default values, and the use of the new information will be optional.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `EntityModel()` | The default constructor for use by subclasses.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.lang.Class` | `classForName​(java.lang.String className)` | Deprecated. use `resolveClass(java.lang.String)` instead.
    `java.lang.Object` | `convertRawObject​(RawObject raw)` | Converts a given raw object to a live object according to the current class definitions.
    `java.util.List<RawType>` | `getAllRawTypes()` | Returns all versions of all known types.
    `java.util.List<RawType>` | `getAllRawTypeVersions​(java.lang.String className)` | Returns all known versions of type information for a given class name, or null if no persistent version of the class is known.
    `abstract ClassMetadata` | `getClassMetadata​(java.lang.String className)` | Returns the metadata for a given persistent class name, including proxy classes and entity classes.
    `abstract EntityMetadata` | `getEntityMetadata​(java.lang.String className)` | Returns the metadata for a given entity class name.
    `abstract java.util.Set<java.lang.String>` | `getKnownClasses()` | Returns the names of all known persistent classes.
    `java.util.Set<java.lang.String>` | `getKnownSpecialClasses()` | Returns the names of all known persistent enum and array classes that may be used to store persistent data.
    `RawType` | `getRawType​(java.lang.String className)` | Returns the type information for the current version of a given class, or null if the class is not currently persistent.
    `RawType` | `getRawTypeVersion​(java.lang.String className, int version)` | Returns the type information for a given version of a given class, or null if the given version of the class is unknown.
    `boolean` | `isOpen()` | Returns whether the model is associated with an open store.
    `void` | `registerClass​(java.lang.Class persistentClass)` | Registers a persistent class, most importantly, a `PersistentProxy` class or entity subclass.
    `java.lang.Class` | `resolveClass​(java.lang.String className)` | Should be called by entity model implementations instead of calling Class.forName whenever loading an application class.
    `protected void` | `setCatalog​(com.sleepycat.persist.impl.PersistCatalog newCatalog)` | Internal access method that should not be used by applications.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### EntityModel

          protected EntityModel()

      The default constructor for use by subclasses.

  - ### Method Detail

    - #### isOpen

          public final boolean isOpen()

      Returns whether the model is associated with an open store.

      The `registerClass(java.lang.Class)` method may only be called when the model is not yet open. Certain other methods may only be called when the model is open:

      - `convertRawObject(com.sleepycat.persist.raw.RawObject)`
      - `getAllRawTypeVersions(java.lang.String)`
      - `getRawType(java.lang.String)`
      - `getRawTypeVersion(java.lang.String, int)`
      Returns:
        whether the model is associated with an open store.

    - #### registerClass

          public final void registerClass​(java.lang.Class persistentClass)

      Registers a persistent class, most importantly, a `PersistentProxy` class or entity subclass. Also registers an enum or array class.

      Any persistent class , enum class or array may be registered in advance of using it, to avoid the overhead of updating the catalog database when an instance of the class is first stored. This method must be called in three cases:

      1. to register all `PersistentProxy` classes, and
      2. to register an entity subclass defining a secondary key, if `getSubclassIndex` is not called for the subclass, and
      3. to register all new enum or array classes, if the these enum or array classes are unknown for DPL but will be used in a Converter mutation.

      For example:

           EntityModel model = new AnnotationModel();
           model.registerClass(MyProxy.class);
           model.registerClass(MyEntitySubclass.class);
           model.registerClass(MyEnum.class);
           model.registerClass(MyArray[].class);

           StoreConfig config = new StoreConfig();
           ...
           config.setModel(model);

           EntityStore store = new EntityStore(..., config);

      This method must be called before opening a store based on this model.

      Parameters:
        `persistentClass` - the class to register.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is associated with an open store.
        `java.lang.IllegalArgumentException` - if the given class is not persistent or has a different class loader than previously registered classes.

    - #### setCatalog

          protected void setCatalog​(com.sleepycat.persist.impl.PersistCatalog newCatalog)

      Internal access method that should not be used by applications. This method is used to initialize the model when catalog creation is complete, and reinitialize it when a Replica refresh occurs. See Store.refresh.
      Parameters:
        `newCatalog` - the catalog.

    - #### getClassMetadata

          public abstract ClassMetadata getClassMetadata​(java.lang.String className)

      Returns the metadata for a given persistent class name, including proxy classes and entity classes.
      Parameters:
        `className` - the class name.
      Returns:
        the metadata or null if the class is not persistent or does not exist.

    - #### getEntityMetadata

          public abstract EntityMetadata getEntityMetadata​(java.lang.String className)

      Returns the metadata for a given entity class name.
      Parameters:
        `className` - the class name.
      Returns:
        the metadata or null if the class is not an entity class or does not exist.

    - #### getKnownClasses

          public abstract java.util.Set<java.lang.String> getKnownClasses()

      Returns the names of all known persistent classes. A type becomes known when an instance of the type is stored for the first time or metadata or type information is queried for a specific class name.
      Returns:
        an unmodifiable set of class names.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### getKnownSpecialClasses

          public java.util.Set<java.lang.String> getKnownSpecialClasses()

      Returns the names of all known persistent enum and array classes that may be used to store persistent data. This differs from `getKnownClasses()`, which does not return enum and array classes because they have no metadata.
      Returns:
        an unmodifiable set of enum and array class names.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### getRawType

          public final RawType getRawType​(java.lang.String className)

      Returns the type information for the current version of a given class, or null if the class is not currently persistent.
      Parameters:
        `className` - the name of the current version of the class.
      Returns:
        the RawType.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### getRawTypeVersion

          public final RawType getRawTypeVersion​(java.lang.String className,
                                                 int version)

      Returns the type information for a given version of a given class, or null if the given version of the class is unknown.
      Parameters:
        `className` - the name of the latest version of the class.
        `version` - the desired version of the class.
      Returns:
        the RawType.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### getAllRawTypeVersions

          public final java.util.List<RawType> getAllRawTypeVersions​(java.lang.String className)

      Returns all known versions of type information for a given class name, or null if no persistent version of the class is known.
      Parameters:
        `className` - the name of the latest version of the class.
      Returns:
        an unmodifiable list of types for the given class name in order from most recent to least recent.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### getAllRawTypes

          public final java.util.List<RawType> getAllRawTypes()

      Returns all versions of all known types.
      Returns:
        an unmodifiable list of types.
      Throws:
        `java.lang.IllegalStateException` - if this method is called for a model that is not associated with an open store.

    - #### convertRawObject

          public final java.lang.Object convertRawObject​(RawObject raw)

      Converts a given raw object to a live object according to the current class definitions.

      The given raw object must conform to the current class definitions. However, the raw type (`RawObject.getType()`) is allowed to be from a different store, as long as the class names and the value types match. This allows converting raw objects that are read from one store to live objects in another store, for example, in a conversion program.

      Parameters:
        `raw` - the RawObject.
      Returns:
        the live object.

    - #### resolveClass

          public java.lang.Class resolveClass​(java.lang.String className)
                                       throws java.lang.ClassNotFoundException

      Should be called by entity model implementations instead of calling Class.forName whenever loading an application class. This method honors the BDB JE environment's ClassLoader property and uses `ClassResolver` to implement the class loading policy.
      Parameters:
        `className` - the class name.
      Returns:
        the Class.
      Throws:
        `java.lang.ClassNotFoundException` - if the class is not found.

    - #### classForName

          @Deprecated
          public static java.lang.Class classForName​(java.lang.String className)
                                              throws java.lang.ClassNotFoundException

      Deprecated.
      use `resolveClass(java.lang.String)` instead. This method does not use the environment's ClassLoader property.
      Parameters:
        `className` - the class name.
      Returns:
        the Class.
      Throws:
        `java.lang.ClassNotFoundException` - if the class is not found.

Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.