Facet Instance

Introduction

Facet Instance is a data structure associated with each incoming request to the TQLEngine. Each facet instance is defined by :

User Specified Facet ID
One of the TQLEngine supported Facet Types
Protocol Handler Name on which the requests will be listening.

Syntax

For Statement Syntax

<NewFacetInstance Fid="User-specified unique identifier" Name="Name of the Facet Instance" Type="FacetType Name">
  <!-- Blocks of Lifecycle stages -->
  <OnActivate/>
  <OnOpen ModifyPipeline="Server-side Name of the Protocol Handler"/>
  <OnRequest/>
  <OnResponse/>
  <OnClose/>
  <OnError/>
</NewFacetInstance>

Syntax Notes

NewFacetInstances are defined within NewPackage definition. A package definition consists of a collection of FacetInstances.
Examples of each of these variations will be provided in the next section.
Incoming requests without valid facet IDs are rejected.

Facet Instance Lifecycle

Once a request legitimacy is established by successful resolution of its facet ID, a processing pipeline is created for low level request processing.

Once request data is presented in a universal fashion (as an instance of ListMap data structure), TQLEngine invokes appropriate facet type method using current connection context and facet instance information as arguments.

The facet lifecycle is the beginning-to-end stages of the facet pipeline that are marked by different facet events. Each facet event can be associated with invoking a method. The actual call arguments will be selected by the TQLEngine by executing the event-specific piece of facet script found in the facet instance. That is, it is possible to specify a correspondent piece of facet script for each facet event. Such facet script may contain simple logic to check some request value or do template-based data transformation before actual java method invocation.

For instance, upon facet instance activation (creation) the TQLEngine will invoke the onActivate method; upon incoming request it will invoke onRequest method and so on.

Event	Description
onActivate	Handler is called by the engine at the of activation of the facet
onDeactivate	Handler is called by the engine at the time of deactivation
onOpen	Handler is called, when facet pipeline is opened
onClose	Handler is called, when facet pipeline if closed
onRequest	Handler is called when the request is received on the pipeline
onResponse	Handler is called when the response is send on the pipeline
onError	If error in pipeline, this handler is called and pipeline gets closed

Facet Instance Examples

NewFacetInstance HelloWorld Example

<NewFacetInstance fid="helloworld" name="HelloWorld" type="SffMsgFacet">
  <OnActivate/>
  <OnOpen ModifyPipeline="HttpServerExtensionArgs"/>
  <OnRequest>
    <DoResponse>
      <Process>
        <Message type="text">
          <Value>
            Hello World from FacetScript!
          </Value>
        </Message>
      </Process>
    </DoResponse>
  </OnRequest>
  <OnResponse/>
  <OnClose/>
</NewFacetInstance>

For FacetScript Language specs, see here.