Using FacetScript

Introduction

The FacetScript Language is one of the Atomic Domain Languages (ADLs).  It is a low level high performance scripting language natively executed by the A-Stack without any additional compilation besides initial parsing.

General Syntax Considerations

FacetScript language as well as other domain-specific languages used in Atomiton A-Stack stack is not bound to a specific syntax. Any syntax capable of expressing structure can be used to represent language constructs. Out of the box, both XML and JSON can be used.

Since JSON does not have a concept of attributes, it follows that compiler does not make any distinction between XML elements and attributes either. That is, any XML attribute can be given as an element and any element with text value can be given as an attribute. JSON also does not allow multiple entries of the same name so these must be expressed as JSON arrays.

Recommended syntax to use is XML.

Keyword Normalization

Before processing, parser will normalize tags to a canonic form so a variety of keyword styles are allowed in the input. For example keywords “NewFacetInstance”, “newfacetinstance”, “NeWfAcEtInStAnCe”, “new-facet-instance” all will be normalized and interpreted as a canonic camel-case “NewFacetInstance”. Note that Keyword Normalization only applies to reserved keywords of FacetScript.

However, this is only true for defined language constructs. Documents may also contain any number of arbitrary attributes (i.e. key-value pairs) possibly organized into nested/hierarchical structures for the purpose of template processing. Such attributes are not normalized as compiler has no knowledge of their meaning. Normally it does not cause any problems as such attributes are not shared across different files.

How is FacetScript Implemented

FacetScript implementation within A-Stack is best understood if we understand the message processing flow within A-Stack.

Message Processing Flow

The Atomiton A-Stack architecture is a Scalable Event-Driven Architecture which uses a high performance NIO-based communication framework that provide low level asynchronous socket communications. Message processing flow steps are:

1. A data structure called Facet Instance is associated with each incoming request. Each facet instance is identified by its facet ID and represents a capability to perform certain actions on the engine.
2. Incoming requests without valid facet IDs are rejected. Each facet instance is also associated with its Facet Type which is a piece of executable code (a Java class) intended to actually process the request
3. Once request legitimacy is established by successful resolution of its facet ID, a processing pipeline is created for low level request processing. This includes protocol handling, data decoding/encoding and initial data transformation and normalization.
4. Once request data is presented in a universal fashion (as an instance of ListMap data structure), engine invokes appropriate facet type method using current connection context and facet instance information as arguments.

When to use FacetScript

Using FacetScript is optional and completely dependent on the developer role. For example, if you are a business analyst responsible for only writing simple TQL queries then using FacetScript is optional.

FacetScript Support in FacetTypes

 <NewFacetInstance fid="[:CONFIG.FsExecutorFid:]" name="Atomiton.FsExecutor" type="SffMsgFacet">
 <OnActivate>
 <ImportFacet>[:CONFIG.CommonMacroFid:]</ImportFacet>
 <!--============ MACROS ==============================================================-->
 <Include>[:Default.Location:]private/macros/fs/reset-fs.mc.xml</Include>
</OnActivate>
</NewFacetInstance>

<Query>
  <Find format="Version">
    <VendorInfo>
      <vendorSysId ne=""/>
    </VendorInfo>
  </Find>
  <For each="val" in="Find.Result.VendorInfo">
    <IF Condition="/'[:$LocalData.val.VendorTitle.Value:]' eq 'Sensor Provider'">
      <Log Message="Found Sensor Provider"/>
    </IF>
    <SetResponseData Key="val.VendorTitle.Value" Value="Actuator Provider"/>
  </For>
  <!-- Do an Update -->
  <Update From="Result">
    <Include>$Response.Message.Value.Find</Include>
  </Update>
</Query>

<Workflow wid="[:CONFIG.WfExecutorWid:]" Limit="1" Live="1">
  <Task name="Executor" while="true">
    <Event name="Argument"/>
    <Invoke name="Execute" waitFor="Argument" fid="[%:Event.Argument.ExeFid:%]">
      <Include>[%:@WFRT:%]Event.Argument.Task</Include>
    </Invoke>
    <Invoke name="SetResult" fid="[:CONFIG.BehaviorFid:]">
      <FacetScript>
        <Process>
          <Message>
            <Value>
              <Set wid="[%:Event.Argument.Response.Wid:%]" target="[%:Event.Argument.Response.Result:%]">
                <Value>
                  <Include>[%:@WFRT:%]Invoke.Execute.Message.Value</Include>
                </Value>
              </Set>
              <Set wid="[%:Event.Argument.Response.Wid:%]" target="[%:Event.Argument.Response.Event:%]" value="true"/>
            </Value>
          </Message>
        </Process>
      </FacetScript>
    </Invoke>
  </Task>
</Workflow>

Mandatory within Package Definition

Using FacetScript is mandatory when defining a new package. New package definition contains the list of FacetTypes that the developer intends to deploy in A-Stack. Note that NewPackage itself is part of FacetScript.

<NewPackage>
<!-- ======================================================================= -->
    <NewFacetInstance fid="test" name="static" type="SffHttpStaticFileFacet">
        <OnActivate>
          <Process>
            <Resource>res</Resource>
          </Process>
        </OnActivate>
    </NewFacetInstance>
<!-- ======================================================================= -->    
    <NewFacetInstance fid="wstest" name="wstest" type="SffTcpFacet" context="keep">
        <OnOpen ModifyPipeline="WebSocketServerExtensionArgs"/>
        <OnRequest>
            <DoResponse target="wstest:*" process="wstest.$Request"/>
        </OnRequest>
    </NewFacetInstance>
<!-- ======================================================================= -->    
</NewPackage>