Package com.orchestranetworks.userservice

# Interface UserServiceObjectContextBuilder

public interface UserServiceObjectContextBuilder
This interface provides methods to register or remove objects managed by the user service. It also allows to define the rich typing of applicative objects that are not persistent, which are neither a record nor a dataset.

Once an object is registered through this interface, it should be used in the other containers provided by `UserService`, with the following protocol:

- On the user interface content generation, to connect a graphical component to a data element, the method `UserServicePaneWriter.setCurrentObject(ObjectKey)` must first be called, to identify the current object. Then widgets can be added, for instance by invoking `addFormNode(Path)`.
- To directly read and write values held by the objects registered through this interface, the interface `ValueContext` and its sub-interfaces should be used. See `UserServiceObjectContext` and `UserServiceObjectContextForInputValidation`.
- On the user submit, the registered record(s) and dataset(s) should be persisted using the methods provided by `UserServiceTransactionManager`.

Since:
  5.8.0
See Also:
  - `UserService.setupObjectContext(UserServiceSetupObjectContext, UserServiceObjectContextBuilder)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `BeanDefinition`
  `createBeanDefinition()`
  Returns a new empty definition that can be used to register a dynamic object (an object not mapped to a JavaBean).
  `BeanDefinition`
  `createBeanDefinition(Class<?> aClassToInstantiate)`
  Returns a new empty definition mapped to a JavaBean.
  `void`
  `registerBean(ObjectKey anObjectKey, BeanDefinition aBeanDefinition)`
  Registers a non-persistent bean object.
  `void`
  `registerBean(ObjectKey anObjectKey, BeanDefinition aBeanDefinition, Object anObject)`
  Registers a non-persistent bean object.
  `void`
  `registerNewDuplicatedRecord(ObjectKey anObjectKey, Adaptation aRecord)`
  Registers a new duplicated record in the object context.
  `void`
  `registerNewRecord(ObjectKey anObjectKey, AdaptationTable aTable)`
  Registers a new record in the object context.
  `void`
  `registerRecordOrDataSet(ObjectKey anObjectKey, Adaptation aRecordOrDataSet)`
  Registers an existing record or dataset in the object context.
  `void`
  `unregisterAllObjects()`
  Unregisters all objects from the object context.
  `void`
  `unregisterObject(ObjectKey anObjectKey)`
  Unregisters an object from the object context.

- ## Method Details

  - ### createBeanDefinition

    BeanDefinition createBeanDefinition()
    Returns a new empty definition that can be used to register a dynamic object (an object not mapped to a JavaBean).

    One or more dynamic object(s) mapped to the definition should then be registered using the method `registerBean(ObjectKey, BeanDefinition)`.

    Returns:
      a new bean definition, to be used to define the model of a dynamic object.

  - ### createBeanDefinition

    BeanDefinition createBeanDefinition(Class<?> aClassToInstantiate)
    Returns a new empty definition mapped to a JavaBean. The definition that will be specified using the returned object must match the specified JavaBean properties (getters and setters) and their Java type.

    One or more JavaBean object(s) mapped to the definition should then be registered using the methods `registerBean(ObjectKey, BeanDefinition)` or `registerBean(ObjectKey, BeanDefinition, Object)`.

    Parameters:
      `aClassToInstantiate` - the class of the JavaBean to instantiate and to map to the element.
    Returns:
      a new bean definition, to be used to define the model corresponding to the specified JavaBean.

  - ### registerBean

    void registerBean(ObjectKey anObjectKey, BeanDefinition aBeanDefinition)
    Registers a non-persistent bean object. A new instance of the object will be created using the defaults specified by the bean definition.
    Parameters:
      `anObjectKey` - the object key. If an object with the same key name already exists, it will be overridden.
      `aBeanDefinition` - the bean definition of the object.

  - ### registerBean

    void registerBean(ObjectKey anObjectKey, BeanDefinition aBeanDefinition, Object anObject)
    Registers a non-persistent bean object.
    Parameters:
      `anObjectKey` - the object key. If an object with the same key name already exists, it will be overridden.
      `aBeanDefinition` - the definition of the bean.
      `anObject` - the instance of the object. Must be of the type specified by the bean definition. If `null`, a new instance of the object will be created using the defaults specified in the schema definition.

  - ### registerRecordOrDataSet

    void registerRecordOrDataSet(ObjectKey anObjectKey, Adaptation aRecordOrDataSet)
    Registers an existing record or dataset in the object context.
    Parameters:
      `anObjectKey` - the object key. If an object with the same key name already exists, it will be overridden.
      `aRecordOrDataSet` - the record or dataset.
    See Also:
      - `UserServiceTransactionManager.save(ObjectKey...)`

  - ### registerNewRecord

    void registerNewRecord(ObjectKey anObjectKey, AdaptationTable aTable)
    Registers a new record in the object context. The record is not yet persisted.
    Parameters:
      `anObjectKey` - the object key. If an object with the same key name already exists, it will be overridden.
      `aTable` - the table that will own the new record.
    See Also:
      - `UserServiceTransactionManager.save(ObjectKey...)`

  - ### registerNewDuplicatedRecord

    void registerNewDuplicatedRecord(ObjectKey anObjectKey, Adaptation aRecord)
    Registers a new duplicated record in the object context. The record is not yet persisted.
    Parameters:
      `anObjectKey` - the object key. If an object with the same key name already exists, it will be overridden.
      `aRecord` - the record to be duplicated.
    Since:
      5.8.1

  - ### unregisterObject

    void unregisterObject(ObjectKey anObjectKey)
    Unregisters an object from the object context. Does nothing if the object does not exist.
    Parameters:
      `anObjectKey` - the object's key.

  - ### unregisterAllObjects

    void unregisterAllObjects()
    Unregisters all objects from the object context.