Create or Update Concepts - learn-tibco-cep/tutorials GitHub Wiki

When a persistent store is specified in its CDD file, a BusinessEvents application will automatically save all new or updated data of concepts/events to the specified data store during post-RTC process, as long as the concept or event type is configured to use cache and/or store in the CDD. The post-RTC process is smart to make small number of database calls to save all entities that are created or updated in a same RTC. Thus, application developers will need to write only code to instantiate or update individual concepts or events. No explicit database call is required.

Concept Instantiation

Concept instances can be created by using the standard catalog functions Instance.createInstance(), Instance.createInstanceFromJSON(), or Instance.createInstanceFromXML(), which allows you to create a new concept by XSLT mapping from events or XML payloads of known XSD, or by direct deserialization of a JSON or XML string. In this tutorial, e.g., the function createRevisions calls Instance.createInstanceFromJSON() to create multiple revisions of a concept from JSON strings.

If a concept contains only small number of properties, it is more efficient to call the auto-generated constructor in Ontology Functions. In this tutorial, e.g., the rule UpdateWork calls the constructor of concept Excerpt.

You may also create an empty concept of a specified type by calling Instance.newInstance(), and then write code to populate the concept with required values. This approach is typically used to create concepts with only key values, or to map only part of input data that does not have a pre-defined schema definition. In this tutorial, e.g., the function createAuthorFromJSON creates an empty concept Author, and then sets its properties by using elements from a JSON document node.

Update Concepts

By convention, concepts in a persistent store are updated by the following steps in a BE application.

• In an event preprocessor function, acquire necessary locks for concepts to be modified, and then load the required concepts from persistent store;
• In one or more rules, implement application logic that modifies the concepts. Rules may also create new concepts and/or fetch other read-only data from persistent stores if necessary;
• Post-RTC process will automatically save the changes of all concepts to the persistent store.

In this tutorial, e.g., the preprocessor function onUpdateConcept first acquires a lock by calling Cluster.DataGrid.Lock(), and then loads a concept from Ignite cache or persistent store by calling Cluster.DataGrid.CacheLoadConceptByExtIdByUri(). The loaded concept is then updated by a rule, e.g., UpdateAuthor.

More complex use cases may require locking and fetching multiple concepts. When multiple locks are required, all locks should be acquired in the event preprocessor function, and the order of acquiring locks must be carefully managed to avoid potential dead locks. Avoid updating concepts in the preprocessor, because only the modifications by a rule are guaranteed to be saved by the Post-RTC process. The page for Query Concepts describes more ways to load concepts from a persistent store.

Call Store Catalog Functions

In some special use cases, you may need to create concepts and save them to a persistent store immediately in an event preprocessor, and so you do not have to rely on the Post-RTC process to save the data asynchronously. You may implement such behavior as follows.

• Create transient concepts by calling Instance.createTransientInstanceXXX() or Instance.newTransientInstance();
• Save the transient concepts by calling Store.Util.put() or Store.Util.putAll().

Since the transient concepts will not be added to the rules working memory, they will be out of the scope once the preprocessor function exits, and thus deleted by GC.