Dynamic Clusters and Properties

You can:

• Add dynamic clusters to a class from the Jade Platform development environment or at run time.

• Add design‑time dynamic properties to a class from the Jade Platform development environment.

• Extract from and load design‑time dynamic properties to a schema (.scm) file.

• Reference design‑time dynamic properties directly in methods.

Add dynamic properties to existing classes to implement new or changed functionality without requiring a database reorganization of installations where the changes are installed. These dynamic properties are displayed and can be used in the same way as static properties, including as key elements in MemberKeyDictionary classes.

You can declare one or more property clusters on a class. Dynamic properties can be added rather than static properties, to avoid the need for a reorganization.

When a dynamic property has been defined, it can be used in most places where static properties can be used; for example, in packages, ODBC, keys, and exposures (but not in RPS, Jade audit access, or ad hoc indexes). The two types of dynamic properties are:

• Runtime dynamic properties, which:

  • Are created, changed, or deleted only at run time by user logic.

  • Do not require any reorganization when added, changed, or deleted.

  • Are displayed in the Jade Platform development environment for a class (the default text color is magenta) but cannot be changed or deleted using the development environment.

  • Are not included in schema (.scm) files with the class.

  • Cannot be directly referred to in Jade methods. Access is by calls to the getPropertyValue and setPropertyValue methods using the property name.

  • Reorganization is not available to handle any impact caused; for example, an added inverse is not populated.

  • Cannot be used in exposures, ODBC, packages, RPS, as keys, in an inverse with a static or design‑time property on the other side, Jade audit access, or a delete command action in a Jade Control File (JCF) commandFile parameter in the batch Schema Load utility (jadloadb).

  For details, see "Runtime Dynamic Properties", in Chapter 21 of the Developer's Reference.

• Design-time dynamic properties, which:

  • Can be created and maintained using the Jade Platform development environment.

  • Are displayed in the development environment for a class (the default text color is maroon).

  • Can be directly accessed in Jade methods.

  • Even if a reorganization is not required when a design‑time dynamic property is added, changed, or deleted, you are given the option of versioning the class and the property if the change was not made in the latest version of a versioned schema.

  • The addition, change, or deletion of a primitive type, exclusive primitive array, or ordinary object reference does not require a reorganization except for the deletion of a non‑embedded property.

    This is the main benefit of using design‑time dynamic properties, as a mutate reorganization is not required in most cases. If versioning is used, the reorganization process needs only to instantiate the new class definition.

  • Reorganization is required when inverses are added and therefore there is really no advantage in adding a design‑time dynamic inverse versus using a static property, unless both sides of the new inverse are new design‑time dynamic properties.

  • Can be used in exposures, ODBC, packages, as keys, in an inverse with a static property on the other side, and in a delete command action in a Jade Control File (JCF) commandFile parameter in the batch Schema Load utility (jadloadb).

  • Cannot be used in RPS, Jade audit access, or as keys in an ad hoc index.

The Window sheet of the Preferences or Jade Installation Preferences dialog enables you to change the color with which the text of dynamic design-time and runtime property names are displayed in the Properties List of a hierarchy browser. By default, design-time dynamic properties are displayed in maroon and runtime dynamic properties in magenta.

For details about defining dynamic property clusters, see "Defining Dynamic Clusters", in Chapter 3. For details about defining dynamic attribute and reference properties, see "Defining a Dynamic Attribute Property" and "Defining a Dynamic Reference Property", respectively, in the following subsections.

The following limitations apply when using dynamic clusters and properties.

• Dynamic properties cannot be added to Collection classes.

• A dynamic property cannot be a subobject (an exclusive collection).

• The transaction that adds a new runtime dynamic property must be committed before the new property can be used. This allows the notification that the property has been added to be sent and processed, and avoids multiple updater conflicts over cluster definition changes.

• A class can have a maximum of 255 local dynamic property cluster definitions.

• A class can have a maximum of 65,535 local properties, both static and dynamic.

• Dynamic property clusters and dynamic properties cannot be added to system schema classes.

When you click the OK button on the Define Dynamic Property or Define Dynamic Reference dialog, a message box similar to that shown in the following image is displayed if the class is not versioned or the selected schema is not the latest.

Clicking:

• Yes versions the schema, class, and cluster if required, and adds the new property to the latest version.

• No adds the property to the current version and the property immediately becomes live and available.

• Cancel aborts the add process and closes the dialog.

A similar message box is displayed if the class is not versioned or the selected schema is not the latest, so that the change can be versioned, directly applied, or aborted.

Deleting a design‑time dynamic property also displays a similar message box if the class is not versioned or the selected schema is not the latest, allowing the delete action to be versioned, directly applied, or aborted. Note that the deletion of a non‑embedded design‑time dynamic property (exclusive, slob, or blob) requires a reorganization to perform the delete action.

The process of changing a dynamic property is the same as that for a static property, except that:

• You cannot change the defined dynamic property cluster.

• You cannot change the type from a primitive type to a collection type, or the reverse.

• You cannot change a collection type if the class has instances, unless you change it to a superclass.

• Primitive type data changes are handled at run time, converting the previous stored type into the new type on a get method call and storing the data in the new format on a set method call.

For details about the scope of design‑time dynamic properties, including a table providing usage decisions, see "Design-Time Dynamic Property Use" and "Deciding Between Static and Design-Time Dynamic Properties".