Fiber is a collection of tools provided as a part of GCF 3, which would help you host a component developed in GCF 3 like a web service. A client written in any technology on any platform can then access the exposed services as long as they follow a simple JSON message format.

Introduction

This article illustrates how Fiber can be used to provide the methods in components as web services; and the message format a client needs to use, to have a meaningful communication with Fiber.

Setting up Fiber at the server

First thing to do, is to get the GCF 3 development environment ready. Refer to GCF 3's FAQ document to read about the same.
Next you would need a web server. Ideally any thing that can run PHP would do just fine. But its worth mentioning here that we have tested it only with Apache on Linux, and Windows.
Update the document root of the web server to point to path-to-GCF3/Fiber/Fiber/Scripts where you must find the PHP files of the Fiber.
Write your web service classes and expose them via writing a GCF component. See Authoring components with services
Update system path with the location of the library files for your component so that it can be found by Fiber when required (Components will be loaded by Fiber only when a client tries to access it for the first time)
Test your set-up by running path-to-GCF3/Tests/UnitTests/FiberTest . If the tests work fine, your set-up is fine.

Starting and stopping Fiber

Fiber can be started/stopped using the command line utility FiberCtl that comes with Fiber.

Start Fiber by executing the following command

FiberCtl start

Now clients should be able to access the web services provided by your component/s over the web!
Stop Fiber by executing the following command

FiberCtl stop

Also FiberCtl status can be used to find out whether Fiber is already running or not

Authoring components with services

In Fiber the web services should be provided through dynamically loadable components. These are normal GCF 3 components with the following rules

The component should be available in a library file
All exposed objects in the component that intends to offer services should have allowmetaaccess property set to true
Only public methods that are invokable (Q_INVOKABLE, slots) in exposed objects would be accessible as services.

The components that host the web services could either be Core or Gui components.

Note: It is strongly adviced that the gui components written to be loaded by Fiber doesn't call show on any widgets. This would make automatic recovery from crash difficult.

Sample core service component

In SimpleCoreComponent.h

#include <GCF3/Component>
#include <GCF3/Application>
class SimpleCoreComponent : public GCF::Component
{
    Q_OBJECT
public:
    SimpleCoreComponent(QObject *parent=0)
        : GCF::Component(parent) {
    }
    Q_INVOKABLE void dummyService() { }
protected:
    void initializeEvent(GCF::InitializeEvent *e) {
        if(e->isPreInitialize())
            return;
        GCF::ObjectTreeNode *node = gAppService->objectTree()->node(this);
        if(node)
            node->writableInfo()["allowmetaaccess"] = true;
    }
    void contentLoadEvent(GCF::ContentLoadEvent *e) {
        if(e->isPreContentLoad())
            e->setContentFile(":/Content/SimpleCoreComponent.xml");
        GCF::Component::contentLoadEvent(e);
    }
    QObject *loadObject(const QString &name, const QVariantMap &) {
        if(name == "Core")
            return this;
        return 0;
    }
};

In SimpleCoreComponent.cpp

#include "SimpleCoreComponent.h"
GCF_EXPORT_COMPONENT(SimpleCoreComponent)

Sample gui service component

In SimpleGuiComponent.h

#include <GCF3/GuiComponent>
class SimpleGuiComponent : public GCF::GuiComponent
{
    Q_OBJECT
public:
    SimpleGuiComponent(QObject *parent = 0)
        :GCF::GuiComponent(parent) {
    }
    
    Q_INVOKABLE void dummyService() { }
protected:
    void initializeEvent(GCF::InitializeEvent *e) {
        if(e->isPreInitialize())
            return;
        GCF::ObjectTreeNode *node = gAppService->objectTree()->node(this);
        if(node)
            node->writableInfo()["allowmetaaccess"] = true;
    }
    void contentLoadEvent(GCF::ContentLoadEvent *e) {
        if(e->isPreContentLoad())
            e->setContentFile(":/Content/SimpleGuiComponent.xml");
        GCF::GuiComponent::contentLoadEvent(e);
    }
    QObject *loadObject(const QString &name, const QVariantMap &) {
        if(name == "Core")
            return this;
        return 0;
    }
};

In SimpleGuiComponent.cpp

#include "SimpleGuiComponent.h"
GCF_EXPORT_COMPONENT(SimpleGuiComponent)

Fiber message format

There are mainly 3 different types of messages that the Fiber recognizes. They are

Note: Some of the message formats discussed below makes use of an integer field called requestID. It might be a better idea to treat it as a string value at the client end, for reliable cross-platform cross-architecture behaviour (as in, store it as a string and don't engage in an integer like manipulation on the same).

Session management request

Session management request messages can be used to request the Fiber for the creation or termination of a dedicated session. Refer to the table below for the message format for constructing a session management request.

Note: Sessions created like this would be terminated only when an explicit terminate request on that session is made. However if you suspect that you would be dealing with irresponsible clients, you should consider configuring the session handler to terminate on a time-out. See Advanced tweaking

Request parameters
Key	Data-type	Possible values
requestType	string	SESSION_MGMT
sessionCommand	string	create - to create a session terminate - to terminate a session
sessionName	string	ID of the session that needs to be terminated. Needs to be specified only for terminate requests
Response parameters
Key	Data-type	Possible values
success	bool	true - if session created successfully false - if session creation failed
result	string	ID of the created session on success; empty string otherwise
error	string	error message on failure; empty string otherwise

Service invocation request

Service invocation requests can be made to the Fiber, to request it to invoke a service and return its response. Depending on whether the request is made as a blocking call or not, Fiber would respond either with the actual result or a requestID which can be used to retrieve the result when it becomes available. We recommend that you use "non-blocking" calls as much as possible, and resort to the "blocking" calls only in the case of extremely simple service methods. Refer to the table below for the message format that is expected.

Note: To see how to retrieve the result of a non-blocking call see Meta method invocation request

Request parameters
Key	Data-type	Possible values
requestType	string	SERVICE_REQUEST
sessionType	string	CORE - to invoke service on a core only session GUI - to invoke service on a gui session
sessionName	string	ID of the session to be used. Leave blank / exclude this field to invoke service on the default session, but this is not recommended
blockingCall	bool	true - if the response should contain the result of invocation false - to receive a requestID as response, which can be used to retrieve the actual response when it becomes available
serviceLibrary	string	Name of the library file that contains the component
serviceComponent	string	Name of the component that contains the service
serviceObject	string	Name of the object in the component that implements the service
serviceMethod	string	Name of the service method
args	list	Array of arguments (maximum 9) to be supplied to the service method. Contents of the list could be a mix of any of the following types - bool, int, double, string, list, map Exclude this parameter if the service method doesn't have a parameter
Response parameters
Key	Data-type	Possible values
success	bool	true - if the service method was invoked successfully false - if service invocation failed
result	bool / int / double / string / list / map	requestID - if the request was not a blocking one result of service method - if the request was a blocking call
error	string	error message on failure; empty string otherwise

Meta method invocation request

This kind of requests can be made to invoke some meta methods on the Fiber. Right now, the meta methods available on the Fiber deals with retrieving the results of non-blocking calls made using Service invocation request. It can also be used to cancel any of the previously made non-blocking requests, for which the results are not downloaded yet.

Request parameters
Key	Data-type	Possible values
requestType	string	SERVICE_REQUEST
sessionType	string	CORE - to invoke service on a core only session GUI - to invoke service on a gui session
sessionName	string	ID of the session to be used. Leave blank / exclude this field to invoke service on the default session, but this is not recommended
metaCall	bool	true
metaMethod	string	availableResponses - to retrieve the list of requestIDs for which results are available responseSize - to retrieve the size of response available for the specified requestID response - to retrieve the specified chunk of response for specified requestID cancelRequests - to cancel the non-blocking method invocation requests for specified list of requestIDs
requestID	int	requestID to be used. Only for responseSize and response meta call
requestIDs	list	list of requestIDs to be used. Only for cancelRequests meta call.
responseLength	int	chunk size in bytes. This is the size of response that would be retrieved from the response available at Fiber. The specified size is sliced from the beginning of response available at the Fiber, and sent back to the client. Only required while making response meta call. Excluding this parameter or specifying -1 as value would result in retrieving the entire response available; and this is not recommended
Response parameters
Key	Data-type	Possible values
success	bool	true - if the service method was invoked successfully false - if service invocation failed
result	int / string / list	Depending on the meta call the result would contain one of the following list of requestIDs for which results are available size of response available (in bytes) for a requestID chunk of response requested list of requestIDs which were cancelled successfully
error	string	error message on failure; empty string otherwise

Accessing Fiber using the message format

Clients can be written to communicate with Fiber in any technology as long as it is possible to

make HTTP requests and receive the corresponding responses
create and interpret JSON objects, represent JSON objects as strings, and construct JSON objects from string.

The ideal flow of events in a client would be

A JSON object, with the necessary key=value pair entries must be created (based on Fiber message format).
The JSON object created in the above step should be converted to a string.
Send the above mentioned string as a request by making an HTTP post request to the address in which Fiber is listening.
Wait for the HTTP response to be available and read it completely.
Treat the received data as plain text, and attempt to create a JSON object out of it.
If the above step succeed, you must be able to extract the result from the object; in the format specified for the corresponding request as discussed in Fiber message format.

Note: Clients should be making requests to the following address http://your-webserver:port/FiberScript.php

Advanced tweaking

Fiber has some configuration options at the server side that can be tweaked and tuned to some extent, so that it can adapt to your requirements.

Configuration settings

The session handler at the Fiber can be configured to terminate automatically, if it remains idle for a specific amount of time. This can be configured by editing the path-toGCF3/Binary/FiberConfig/FiberRequestHandler.ini file.

Hooks in PHP script

Fiber has provisions for inserting additional policing of requests, like security check, before Fiber handles any data. There are hooks from the Fiber's PHP scripts that would be invoked, before and after processing any request received. You could place calls to your own routines, in these hooks so that additional features like security checking can be implemented, if necessary. To do this refer to the file path-to-GCF3/Fiber/Fiber/Scripts/FiberAccessHooks.php.

- postReceiveRequest will be called immediately after receiving the request.
- postProcessRequest will be called immediately after processing the request and before sending the response to the client.
- postSendResponse will be called immediately after sending the response to the client