Facet Instance


Introduction

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

  • User Specified Facet ID
  • One of the A-Stack 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), A-Stack 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 A-Stack 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 A-Stack will invoke the onActivate method; upon incoming request it will invoke onRequest method and so on.

EventDescription
onActivateHandler is called by the engine at the of activation of the facet
onDeactivateHandler is called by the engine at the time of deactivation
onOpenHandler is called, when facet pipeline is opened
onCloseHandler is called, when facet pipeline if closed
onRequestHandler is called when the request is received on the pipeline
onResponseHandler is called when the response is send on the pipeline
onErrorIf error in pipeline, this handler is called and pipeline gets closed

Facet Instance Example

The “Hello, World” program is traditionally used to introduce a programming language. Here is an example of Hello, World in FacetScript:

NewFacetInstance HelloWorld Example
<NewPackage>
<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>
</NewPackage>

Once the NewFacetInstance is deployed on A-Stack following EndPoint will be generated:

http://localhost:8080/fid-helloworld

which produces HTTP Response as

Hello World from FacetScript!

For FacetScript Language specs, see here.