Runtime definition updates

When the toolkit initializes, externalizers read all the definition files and store all the object definitions in memory in a tag structure. The externalizers exploit this structure to create different Java objects depending on the value of their definitions. This creates a problem when you must modify one of these memory definitions because you must stop the toolkit, make the modification to the appropriate definition file, and then restart and re-initialize the toolkit to implement the changes. This process may be acceptable in a development environment but there are other scenarios, such as a high-availability production environment, where you want to avoid the stop and re-initialize process.

The reset process allows you to make minor changes to the memory definitions in runtime. An example of a minor change is updating a self-defined processor when this change involves data or formats used only by this processor and cannot affect other processors. If you must make major changes that may affect the rest of the application, however, you should stop and re-initialize the toolkit. An example of a major change is changing generic definitions that may affect the overall system. Use the reset process with care and only when the changes affect a controlled atomic set of definitions.

When using the reset process, do the following to ensure that it works properly:

How reset works in data, format, context, and service externalizers

How reset works in processor externalizers

How reset works in the typed data externalizer

How the reset process resolves references

The reset process for the data, format, context, and service externalizers can update their tags in memory using an updated file, add definitions if they do not exist, and remove definitions from memory. The following table summarizes what happens when you reset a definition. In the table, def1 is the definition in memory and def1' is the updated definition. A hyphen indicates no definition. The first column of the table shows the definition in memory before the reset process, the second column contains the updated definition, and the last column describes what the reset process did.

Definition in memory	Updated file	Reset action
def1	def1'	Updates def1to def1'
-	def1'	Adds def1to def1'
def1	-	Deletes def1
-	-	Logs a trace message because def1 does not exist in memory or in the file.

Runtime definition updates

The reset process for the processor externalizers can update their tags in memory using an updated file, add definitions if they do not exist, and remove definitions from memory. The modularity of the processor determines whether the definitions in memory are generic or self-defined and which type of file you would use to reset the definition. The following tables summarize what happens when you reset a definition. In the tables, def1 is the definition in memory and def1' is the updated definition. A hyphen indicates no definition.

Generic definition in memory	Self-defined definition in memory	Updated file for generic definition	Updated file for self-defined definition	Reset action
def1	-	def1'	-	Updates def1 in the generic definitions if the toolkit modularity is grouped or mixed. You cannot have a generic definition in memory when the processor has a split modularity.
-	def1	-	def1'	Updates def1 in the self-defined definitions if the processor modularity is split or mixed. You cannot have a self-defined definition in memory and in a grouped configuration.

Generic definition in memory	Self-defined definition in memory	Updated file for generic definition	Updated file for self-defined definition	Reset action
-	-	def1'	-	Adds def1 in the generic definitions if the processor modularity is grouped or mixed. Throws an exception if the modularity is split because def1 does not exist in the self-defined definitions stored in memory or in a file.
-	-	-	def1'	Adds def1 in the self-defined definitions if the processor modularity is split or mixed. Throws an exception if the processor modularity is grouped because def1 does not exist in generic definitions stored in memory or in a file.

Generic definition in memory	Self-defined definition in memory	Updated file for generic definition	Updated file for self-defined definition	Reset action
def1	----	----	----	Deletes def1 in the generic definitions if the processor modularity is grouped or mixed. You cannot have a generic definition in memory when the processor has a split modularity
----	def1	----	----	Deletes def1 in the self-defined definitions if the processor modularity is split or mixed. You cannot have a self-defined definition in memory and in a grouped configuration

Runtime definition updates

The typed data externalizer differs from other externalizers because it does not maintain the list of tags stored during the initialization process. Therefore, it does not use tag instances to create the type instances when required. Instead, it keeps a list of type instances (which it creates from the tags read during initialization) and uses the list to instantiate the typed data element from a type. For this reason, the reset process for the type externalizer differs slightly from the other externalizers.

When an application requests a change to a type definition in the type externalizer, the type externalizer goes to the type instance and modifies it according to the new definition. Once the externalizer has modified the definition, whenever the externalizer instantiates a typed data element from that type, it uses the new type definition.

The reset process modifies a type definition instead of replacing it. The reset process does this so that it can automatically update other types with property descriptors pointing to the modified type provided the descriptors do not override anything in the referred type. The toolkit allows this because these descriptors maintain the same type instance. If the property descriptors do have any extra definition to override, the reset process does not automatically update the default descriptor for that type with the new type definition.

If the modifications to a type includes adding references to other types, the reset process recursively resolves these references. If these references point to new type definitions, they must also be in the file or the reset process throws an exception.

Removing a type definition removes all the information that the instance contained but it does not remove the type instance itself. This has the following impact:

▪ Future readObject calls for the empty type are not be able to instantiate a data element for that type. In this case, the method throws an exception.

▪ Types that contain references to the removed type keep the reference but the reference points to the empty type. Future readObject calls for these types instantiate typed data elements according to the empty referenced types.

Runtime definition updates

During the initialization of the toolkit, the externalizers resolved tag linking references. This modifies the tag structure in memory so that all the reference tags pointing to the same entity point to the same tag definition instance. To dynamically update the tag structure in memory, the reset process does the following:

1 The reset process creates a temporary externalizer. The temporary externalizer performs tag linking in the same way that the other externalizers perform tag linking during the initialization of the toolkit. The difference is that the temporary externalizer uses the definition files that contain the updated definitions. In this way, the reset process creates a parallel tag structure and its reference tag definitions point to the new tag definition instances created in the new temporary tag structure.

2 The reset process compares the tag structure in the temporary externalizer with the tag structure in the original externalizer to determine which tag definitions in the externalizer it needs to modify.

3 The reset process modifies all the attributes of the original tag instance with the attributes of the new tag instance definition. In this way, all the references to the modified entity in the original externalizer see the modification.

For example, the definitions for an entity called B have been updated in the definition file. In the following table, the "Before the update" column shows the file and tag structure in memory before the update was made. The "After the update" column shows the changes in the file and the tag structure in the temporary externalizer. The numbers in parentheses are the instance numbers of the tags.

	Before the update	After the update
Definition file	<kColl id="A"> <refData refId="B"/> </kColl> <field id="B"/>	<kColl id="A"> <refData refId="B"/> </kColl> <kColl id="B"> <refData refId="C"/> <refData refId="D"/> </kColl> <field id="C" /> <field id="D" />
Tag structure	Tag A(1) subtag of A(2) Tag B(2)	Tag A(3) subtag of A(4) Tag B(4) subtag of B(5) subtag of B(6) Tag C(5) Tag D(6)

The tag structure in the original externalizer after performing the reset process on the B definition is:

There is a limitation to the reset process as the following example demonstrates:

	Before the update	After the update
Definition file	<kColl id="A"> <refData refId="C"/> </kColl> <kColl id="B"> <refData refId="C"/> <refData refId="D"/> </kColl> <field id="C"/> <field id="D"/>	<kColl id="A"> <refData refId="C"/> </kColl> <kColl id="B"> <refData refId="C"/> <refData refId="D"/> <refData refId="E"/> </kColl> <field id="C"/> <field id="D"/> <field id="E"/>
Tag structure	Tag A(1) subtag of A(3) Tag B(2) subtag of B(3) subtag of B(4) Tag C(3) Tag D(4)	Tag A(5) subtag of A(7) Tag B(6) subtag of B(7) subtag of B(8) subtag of B(9) Tag C(7) Tag D(8) Tag E(9)

The tag structure in the externalizer after performing the reset process on the B definition followed by doing the reset process on the C definition.

The reset process updates tag instance 3 but only propagates the change in entity A. The reset process does not propagate the change in entity B because the reset process has changed the instance number back to 3 and the entity B still points to tag instance number 7.