Component Class Reference

#include <Fuoten/API/Component>

Inheritance diagram for Component:

Public Types
enum	ExpectedJSONType : quint8 { Empty = 0 , Array = 1 , Object = 2 }

Properties
Fuoten::AbstractConfiguration *	configuration
Fuoten::Error *	error
bool	inOperation
Fuoten::AbstractNotificator *	notificator
quint16	requestTimeout
Fuoten::AbstractStorage *	storage
bool	useStorage
Fuoten::WipeManager *	wipeManager

Public Member Functions
	Component (QObject *parent=nullptr)
	~Component () override
AbstractConfiguration *	configuration () const
Error *	error () const
virtual Q_INVOKABLE void	execute ()=0
bool	inOperation () const
bool	isUseStorageEnabled () const
AbstractNotificator *	notificator () const
quint16	requestTimeout () const
void	setConfiguration (AbstractConfiguration *nAbstractConfiguration)
void	setNotificator (AbstractNotificator *notificator)
void	setRequestTimeout (quint16 seconds)
void	setStorage (AbstractStorage *localStorage)
void	setUseStorage (bool useStorage)
void	setWipeManager (WipeManager *wipeManager)
AbstractStorage *	storage () const
WipeManager *	wipeManager () const

Signals
void	configurationChanged (Fuoten::AbstractConfiguration *configuration)
void	errorChanged (Fuoten::Error *error)
void	failed (Fuoten::Error *error)
void	inOperationChanged (bool inOperation)
void	notificatorChanged (Fuoten::AbstractNotificator *notificator)
void	requestTimeoutChanged (quint16 requestTimeout)
void	sslErrors (QNetworkReply *reply, const QList< QSslError > &errors)
void	storageChanged (Fuoten::AbstractStorage *storage)
void	succeeded (const QJsonDocument &result)
void	useStorageChanged (bool useStorage)
void	wipeManagerChanged (Fuoten::WipeManager *wipeManager)

Static Public Member Functions
static AbstractConfiguration *	defaultConfiguration ()
static AbstractNotificator *	defaultNotificator ()
static AbstractStorage *	defaultStorage ()
static WipeManager *	defaultWipeManager ()
static AbstractNamFactory *	networkAccessManagerFactory ()
static void	setDefaultConfiguration (AbstractConfiguration *config)
static void	setDefaultNotificator (AbstractNotificator *notificator)
static void	setDefaultStorage (AbstractStorage *storage)
static void	setDefaultWipeManager (WipeManager *wipeManager)
static void	setNetworkAccessManagerFactory (AbstractNamFactory *factory)

Protected Member Functions
void	addRequestHeader (const QByteArray &headerName, const QByteArray &headerValue)
void	addRequestHeaders (const QHash< QByteArray, QByteArray > &headers)
virtual bool	checkInput ()
virtual bool	checkOutput ()
virtual void	extractError (QNetworkReply *reply)
QJsonDocument	jsonResult () const
void	notify (AbstractNotificator::Type type, QtMsgType severity, const QVariant &data) const
void	notify (const Error *e) const
QHash< QByteArray, QByteArray >	requestHeaders () const
void	sendRequest ()
void	setApiRoute (const QString &route)
void	setApiRoute (const QStringList &routeParts)
void	setError (Error *nError)
void	setExpectedJSONType (ExpectedJSONType type)
void	setInOperation (bool nInOperation)
void	setNetworkOperation (QNetworkAccessManager::Operation operation)
void	setPayload (const QByteArray &payload)
void	setPayload (const QJsonObject &payload)
void	setRequestHeaders (const QHash< QByteArray, QByteArray > &headers)
void	setRequiresAuth (bool reqAuth)
void	setUrlQuery (const QUrlQuery &query)
virtual void	successCallback ()=0

Detailed Description

Base class for all API requests.

This is the base class for all other classes that implement API operations. Most important property to set when using this class or derived classes is the configuration property. This can either be done per instance direclty via the property or on a global scope via setDefaultConfiguration(). The storage property can be set on a global scope via setDefaultStorage(). Pointers to configuration and storage that are set directly to an instance of a Component subclass via the property setter functions setStorage() and setConfiguration() will take precedence over the default ones.

To modify the QNetworkAccessManager that will be used to perform the network requests, create a subclass of AbstractNamFactory and set it via Component::setNetworkAccessManagerFactory(). This will than be used to create new QNetworkAccessManager instances on the fly that will be children of the Component object.

When creating a subclass of Component, you have to reimplement successCallback(), extractError() and checkOutput(). Optionally you should reimplement checkInput() if your derived class provides own input properties that should be checked before starting the network request.

When reimplementing checkOutput() and checkInput() you have to call the implementations of the class from which you derive to also include their checks and perform some basic operations. In the function that starts the request, set setInOperation() to true and call sendRequest(). In your error handling and successCallback() functions you should afterwards set inOpeartion back to false.

In your reimplementation of successCallback() you should work on the content requested from the News App API that can be obtained by jsonResult(). The content returned by jsonResult() will be set by Component::checkOutput().

In the constructor of your class you should set the API route to use and the expected result, that will be checked by Component::checkOutput().

Component and its subclasses in libfuoten using a shared D-pointer.

Subclassing exmaple

#include <Fuoten/component.h>
#include <Fuoten/error.h>
 
class MyClass : public Fuoten::Component
{
    Q_OBJECT
public:
    MyClass(QObject *parent = nullptr);
 
    void get();
 
protected:
    void successCallback() override;
    void extractError(QNetworkReply *reply) override;
    bool checkOutput() override;
 
private:
    Q_DISABLE_COPY(MyClass)
};
 
 
MyClass::MyClass(QObject *parent) : Fuoten::Component(parent)
{
    setApiRoute(QStringLiteral("/route"));
    setExpectedJSONType(Component::Object);
    setNetworkOperation(QNetworkAccessManager::GetOperation);
};
 
void MyClass::execute()
{
    if (inOperation()) {
        return;
    }
 
    setInOperation(true);
 
    sendRequest();
}
 
 
void MyClass::successCallback()
{
    const QJsonDocument r = jsonResult();
 
    // operate on the result
    // or use a reimplementation of AbstractStorage
 
    setInOperation(false);
 
    emit succeeded(r);
}
 
 
void MyClass::extractError(QNetworkReply *reply)
{
    setError(new Fuoten::Error(reply, this));
    emit failed(error());
}
 
 
bool MyClass::checkOutput()
{
    const QJsonObject o = jsonResult().object();
 
    if (Fuoten::Component::checkOutput()) {
 
        if (!o.contains(QStringLiteral("my_important_value"))) {
            setError(new Fuoten::Error(Fuoten::Error::OutputError, Fuoten::Error::Critical, tr("Can not find that really important value in the server reply."), QString(), this));
            emit failed(error());
            return false;
        } else {
            return true;
        }
 
    } else {
        return false;
    }
}

Member Enumeration Documentation

ExpectedJSONType

enum ExpectedJSONType : quint8

Defines the expected JSON type.

Enumerator
Empty	Expects an empty body in the reply.
Array	Expects a JSON array in the reply body.
Object	Expects a JSON object in the reply body.

Property Documentation

configuration

Fuoten::AbstractConfiguration * configuration

readwrite

Pointer to an AbstractConfiguration derived object.

It is mandatory for all calls to set this property to a valid object that provides the authentication information for the server.

This property can not be changed while Component::inOperation() returns true.

If no configuration object has been set via setConfiguration(), the one set via Component::setDefaultConfiguration() will be the value of this property (if a default one has been set). Configuration objects that are set per instance via setConfiguration() will take precedence over the default ones set via Component::setDefaultConfiguration().

Access functions:

AbstractConfiguration*	configuration() const
void	setConfiguration(AbstractConfiguration *nAbstractConfiguration)

Notifier signal:

void	configurationChanged(AbstractConfiguration *configuration)

error

Fuoten::Error * error

read

Pointer to an error object, if any error occurred.

If no error occurred, it will return a nullptr. The error is set internally by setError().

Access functions:

Error*

error() const

Notifier signal:

void	errorChanged(Error *error)

inOperation

bool inOperation

read

Returns true while the request is in operation.

See also

setInOperation()

Access functions:

bool	inOperation() const

Notifier signal:

void	inOperationChanged(bool inOperation)

notificator

Fuoten::AbstractNotificator * notificator

readwrite

Pointer to an object derived from AbstractNotificator.

Set a notificator to notify users about errors and events. This is not mandatory. You have to derive your own notificator that uses the notification system of the target platform.

If no notificator has been set via setNotificator(), the one set via Component::setDefaultConfigurator() will be used - if any has been set. If you do not set a notificator either per instance or global, this property will hold a nullptr. If a notificator is set to an instance of this class via setNotificator(), this notificator will take precedence over the global default notificator object (if any set).

Access functions:

• AbstractNotificator* notificator() const
• void setNotificator(AbstractNotificator *notificator);

Notifier signal:

• void notificatorChanged(AbstractNotificator *notificator);

See also

notify()

requestTimeout

quint16 requestTimeout

readwrite

Timeout in seconds for network requests.

If you set the timeout to 0, it wil be disabled. Default value: 120 seconds

Access functions:

quint8	requestTimeout() const
void	setRequestTimeout(quint8 nRequestTimeout)

Notifier signal:

void	requestTimeoutChanged(quint8 requestTimeout)

storage

Fuoten::AbstractStorage * storage

readwrite

Pointer to an AbstractStorage derived object.

Set a storage handler to store the results of API requests. You have to derive your own storage from AbstractStorage. Have a look at SQLiteStorage for an example implementation.

This property can not be changed while Component::inOperation() returns true.

If no storage object has been set via setStorage() the one set via Component::setDefaultStorage() will be the value of this property. So if you do not set a storage object through one the methods, this property will hold a nullptr. If a storage object ist set to an instance of this class via setStorage(), this storage object will take precedence over the default storage object (if any set).

Together with the useStorage property, this can be used in the successCallback() function to determine if the API request result should be processed through the local storage object or not.

Access functions:

AbstractStorage*	storage() const
void	setStorage(AbstractStorage *nStorageHandler)

Notifier signal:

void	storageChanged(AbstractStorage *storage)

useStorage

bool useStorage

readwrite

If true (the default), a local storage should be used in the successCallback() function to further process the request results.

Setting this property to false will omit possible usage of local storage objects in the successCallback() function. Even if a defaultStorage() has been set through setDefaultStorage(), it will not be used if this propery ist false.

Access functions:

• bool isUseStorageEnabled() const
• void setUseStorage(bool useStorage)

Notifier signal:

• void useStorageChanged(bool useStorage)

wipeManager

Fuoten::WipeManager * wipeManager

readwrite

Pointer to a WipeManager to handle remote wipe requests.

Set a wipe manager to handle remote wipe requests. This is not mandatory. If no wipe manager has been set via setWipeManager(), the one set via Component::setDefaultWipeManager() will be used - if any has been set. If you do not set a wipe manager either per instance of global, this property will hold a nullptr as default. If a wipe manager is set to an instance of thsi class via setWipeManager(), this wipe manager will take precedence over the global default wipe manager object (if any set).

Access functions:

• WipeManager* wipeManager() const
• void setWipeManager(WipeManager *wipeManager)

Notifier signal:

• void wipeManagerChanged(WipeManager *wipeManager)

Constructor & Destructor Documentation

Component()

Component ( QObject * parent = nullptr )

explicit

Constructs a component with the given parent.

~Component()

~Component ( )

override

Destroys the Component object.

Member Function Documentation

addRequestHeader()

void addRequestHeader ( const QByteArray & headerName, const QByteArray & headerValue )

protected

Adds a header to the HTTP request.

See also

addRequestHeaders(), setRequestHeaders(), requestHeaders()

Parameters

headerName	the name of the header entry
headerValue	the value of the header entry

addRequestHeaders()

void addRequestHeaders ( const QHash< QByteArray, QByteArray > & headers )

protected

Adds headers to the HTTP request.

See also

addRequestHeader(), setRequestHeaders(), requestHeaders()

Parameters

headers

dictionary with key as header name and value as header value

checkInput()

bool checkInput ( )

protectedvirtual

Performs basic input checks.

Reimplement this in a subclass and call the parent's class implementation from there. The basic implementation checks for valid configuration property and basic server and user settings.

Reimplemented in CreateFeed, CreateFolder, DeleteFeed, DeleteFolder, GetItems, GetUpdatedItems, GetWipeStatus, LoginFlowV2, MarkAllItemsRead, MarkFeedRead, MarkFolderRead, MarkItem, MarkMultipleItems, MoveFeed, PostWipeSuccess, RenameFeed, RenameFolder, StarItem, and StarMultipleItems.

checkOutput()

bool checkOutput ( )

protectedvirtual

Performs basic output checks.

Reimplement this in a subclass and call the parent's class implementation from there. The basic implementation extracts the JSON body, if there is data expected (setExpectedJSONType() is not set to Empty) and checks if the expected JSON data type can be found.

Reimplemented in CreateFeed, CreateFolder, GetFeeds, GetFolders, GetItems, GetStatus, GetUpdatedItems, GetUser, and GetVersion.

configuration()

AbstractConfiguration * configuration

(

)

const

Returns a pointer to the AbstractConfiguration that is currently set.

See also

configuration

configurationChanged

void configurationChanged ( Fuoten::AbstractConfiguration * configuration )

signal

This signal is emitted when the pointer to the AbstractConfiguration object changes.

See also

configuration

defaultConfiguration()

AbstractConfiguration * defaultConfiguration ( )

static

Returns the global default configuration.

See also

setDefaultConfiguration()

defaultNotificator()

AbstractNotificator * defaultNotificator ( )

static

Returns the global default notificator.

See also

setDefaultNotificator()

defaultStorage()

AbstractStorage * defaultStorage ( )

static

Returns the global default storage.

See also

setDefaultStorage()

defaultWipeManager()

WipeManager * defaultWipeManager ( )

static

Rerturns the global default wipe manager.

See also

setDefaultWipeManager()

error()

Error * error

(

)

const

Returns a pointer to an Error object, if any error occurred.

Will return a nullptr if no error occurred.

See also

error

errorChanged

void errorChanged ( Fuoten::Error * error )

signal

This signal is emitted when the pointer to the Error object changes. error will be a nullptr if no error occurred or the current error has been reset.

See also

error

execute()

virtual Q_INVOKABLE void execute ( )

pure virtual

Executes the API request.

Reimplement this in a subclass to prepare the request and start it by calling sendRequest().

Implementation example

void RenameFolder::execute()
{
    if (inOperation()) {
        qWarning("Operation is still running.");
        return;
    }
 
    setInOperation(true);
 
    QStringList routeParts;
    routeParts << QStringLiteral("folders") << QString::number(folderId());
    setApiRoute(routeParts);
 
    QJsonObject jsonPayload;
    jsonPayload.insert(QStringLiteral("name"), newFolderName());
    setPayload(jsonPayload);
 
    sendRequest();
}

Implemented in ConvertToAppPassword, CreateFeed, CreateFolder, DeleteAppPassword, DeleteFeed, DeleteFolder, GetFeeds, GetFolders, GetItems, GetServerStatus, GetStatus, GetUpdatedItems, GetUser, GetVersion, GetWipeStatus, LoginFlowV2, MarkAllItemsRead, MarkFeedRead, MarkFolderRead, MarkItem, MarkMultipleItems, MoveFeed, PostWipeSuccess, RenameFeed, RenameFolder, StarItem, and StarMultipleItems.

extractError()

void extractError ( QNetworkReply * reply )

protectedvirtual

Extracts error data from the network reply.

Reimplement this in a subclass to extract errors from the request result. The simplest implementation is to create a new Error object from the QNetworkReply and set it to the Component::error property. You should than also emit the failed() signal.

The basic implementation uses the overloaded Error constructor to extract reply errors, sets the new Error to the error property, sets inOperation to false and emits the failed() signal.

Implementation example

void GetStatus::extractError(QNetworkReply *reply)
{
    setError(new Error(reply, this));
    setInOperation(false);
    Q_EMIT failed(error());
}

Reimplemented in ConvertToAppPassword, CreateFeed, CreateFolder, DeleteFeed, DeleteFolder, MarkFeedRead, MarkFolderRead, MarkItem, MoveFeed, RenameFeed, RenameFolder, and StarItem.

failed

void failed ( Fuoten::Error * error )

signal

Emit this signal in a subclass when the request failed for some reason.

See also

error

Parameters

error

pointer to an Error object

inOperation()

bool inOperation

(

)

const

Returns true while the API request is running.

This might also include the local storage operation, if Component::storage is set to a valid AbstractStorage sublcass.

See also

inOperation

inOperationChanged

void inOperationChanged ( bool inOperation )

signal

This signal is emitted when the in operation status changes.

See also

inOperation

isUseStorageEnabled()

bool isUseStorageEnabled

(

)

const

Getter function for the useStorage property.

See also

setUseStorage(), useStorageChanged()

jsonResult()

QJsonDocument jsonResult ( ) const

protected

Returns the JSON result document.

networkAccessManagerFactory()

AbstractNamFactory * networkAccessManagerFactory ( )

static

Returns the currently set network access manager factory.

See also

setNetworkAccessManagerFactory()

notificator()

AbstractNotificator * notificator

(

)

const

Getter function for the notificator property.

See also

setNotificator(), notificatorChanged()

notificatorChanged

void notificatorChanged ( Fuoten::AbstractNotificator * notificator )

signal

Notifier signal for the notificator property.

See also

setNotificator(), notificator()

notify() [1/2]

void notify ( AbstractNotificator::Type type, QtMsgType severity, const QVariant & data ) const

protected

Checks if a notificator has been set and will use it to notify the user.

See also

AbstractNotificator::notify(AbstractNotificator::Type type, QtMsgType severity, const QVariant &data)

notify() [2/2]

void notify ( const Error * e ) const

protected

Checks if a notificator has been set and will use it to notify about an occured error.

See also

AbstractNotificator::notify(const Error *e)

requestHeaders()

QHash< QByteArray, QByteArray > requestHeaders ( ) const

protected

Returns the currently set HTTP headers for the request.

See also

setRequestHeaders(), addRequestHeader(), addRequestHeaders()

requestTimeout()

quint16 requestTimeout

(

)

const

Returns the currently set request timeout.

See also

requestTimeout

requestTimeoutChanged

void requestTimeoutChanged ( quint16 requestTimeout )

signal

This signal is emitte when the timeout for the request changes.

See also

requestTimeout

sendRequest()

void sendRequest ( )

protected

Sends the request to the server.

setApiRoute() [1/2]

void setApiRoute ( const QString & route )

protected

Sets the API route.

See also

apiRoute()

Parameters

route

complete API route starting with "/"

setApiRoute() [2/2]

void setApiRoute ( const QStringList & routeParts )

protected

Sets the API route constructed from a route part list.

The parts in the QStringList will be joind with a '/' into the API route path.

See also

apiRoute()

Parameters

routeParts

list of route parts that will be joined with a '/'.

setConfiguration()

void setConfiguration

(

AbstractConfiguration *

nAbstractConfiguration

)

Sets a pointer to a AbstractConfiguration to use for the API request.

See also

configuration

setDefaultConfiguration()

void setDefaultConfiguration ( AbstractConfiguration * config )

static

Sets the global default configuration.

See also

defaultConfiguration()

setDefaultNotificator()

void setDefaultNotificator ( AbstractNotificator * notificator )

static

Sets the global default notificator.

See also

defaultNotificator()

setDefaultStorage()

void setDefaultStorage ( AbstractStorage * storage )

static

Sets the global default storage.

See also

defaultStorage()

setDefaultWipeManager()

void setDefaultWipeManager ( WipeManager * wipeManager )

static

Sets the global default wipe manager.

See also

defaultWipeManager()

setError()

void setError ( Error * nError )

protected

Sets the pointer of the error property.

If there was already an error set, the old Error will be deleted.

See also

error

setExpectedJSONType()

void setExpectedJSONType ( ExpectedJSONType type )

protected

Sets the expected JSON type for initial output check.

Default: Empty

See also

expetedJSONType()

setInOperation()

void setInOperation ( bool nInOperation )

protected

Sets the value of the inOperation property.

Use this in subclasses of Component to indicate, that the request is still running or has been finished.

See also

inOperation

setNetworkAccessManagerFactory()

void setNetworkAccessManagerFactory ( AbstractNamFactory * factory )

static

Sets the network access manager factory. The factory will be used to create QNetworkAccessManager objects on demand. If no factory is set, a default QNetworkAccessManager object will be created. The Component class will take ownership of the created QNetworkAccessManager.

See also

networkAccessManagerFactory()

setNetworkOperation()

void setNetworkOperation ( QNetworkAccessManager::Operation operation )

protected

Sets the operation the network manager should perform for this call.

Default: QNetworkAccessManager::GetOperation

Parameters

operation

the type of the nework operation

setNotificator()

void setNotificator

(

AbstractNotificator *

notificator

)

Setter function for the notificator property.

See also

notificator(), notificatorChanged()

setPayload() [1/2]

void setPayload ( const QByteArray & payload )

protected

Sets the payload for the request.

Parameters

payload

the JSON payload to send with the request

setPayload() [2/2]

void setPayload ( const QJsonObject & payload )

protected

Sets the payload for the request.

Parameters

payload

the JSON payload to send with the request

setRequestHeaders()

void setRequestHeaders ( const QHash< QByteArray, QByteArray > & headers )

protected

Sets the headers to use for the HTTP request.

See also

requestHeaders(), addRequestHeader(), addRequestHeaders()

Parameters

headers

dictionary with key as header name and value as header value

setRequestTimeout()

void setRequestTimeout

(

quint16

seconds

)

Sets the timeout for the API request in seconds.

See also

requestTimeout

setRequiresAuth()

void setRequiresAuth ( bool reqAuth )

protected

Set this to true if the request requires authentication.

Default: true

setStorage()

void setStorage

(

AbstractStorage *

localStorage

)

Setter function for the storage property.

See also

storage(), setDefaultStorage(), storageChanged()

setUrlQuery()

void setUrlQuery ( const QUrlQuery & query )

protected

Sets the URL query for the request.

Parameters

query

the query to append to the request URL

setUseStorage()

void setUseStorage

(

bool

useStorage

)

Setter function for the useStorage property.

See also

isUseStorageEnabled(), useStorageChanged()

setWipeManager()

void setWipeManager

(

WipeManager *

wipeManager

)

Setter function for the wipeManager property.

See also

wipeManager(), wipeManagerChanged()

sslErrors

void sslErrors ( QNetworkReply * reply, const QList< QSslError > & errors )

signal

This signal is emitted if the SSL/TLS session encountered errors during the set up.

Will only be emitted if AbstractConfiguration::getIgnoreSSLErrors() returns false (the default).

Parameters

reply	the network reply that cause the SSL error
errors	list of occured SSL errors

storage()

AbstractStorage * storage

(

)

const

Getter function for the storage property.

See also

setStorage(), setDefaultStorage(), storageChanged()

storageChanged

void storageChanged ( Fuoten::AbstractStorage * storage )

signal

Notifier signal for the storage property.

See also

storage(), setDefaultStorage(), setStorage()

succeeded

void succeeded ( const QJsonDocument & result )

signal

Emit this signal in a subclass when the request was successful.

Parameters

result

JSON data replied by the server as result of an API request

successCallback()

virtual void successCallback ( )

protectedpure virtual

Processes the request data if the request was successful.

Reimplement this in a subclass to extract the data from the JSON reply and optionally use the AbtractStorage provided by Component::storage property to store the requested data.

Setting the storage is optional, so you should check if it contains a valid pointer.

In the successCallback you should also set inOperation to false and emit the succeeded() signal (or a custom succeeded signal).

Implementation example

void RenameFolder::successCallback()
{
    if (isUseStorageEnabled() && storage()) {
        storage()->folderRenamed(folderId(), newName());
    }
 
    setInOperation(false);
 
    Q_EMIT succeeded(folderId(), newName());
}

Implemented in ConvertToAppPassword, CreateFeed, CreateFolder, DeleteAppPassword, DeleteFeed, DeleteFolder, GetFeeds, GetFolders, GetItems, GetServerStatus, GetStatus, GetUpdatedItems, GetUser, GetVersion, GetWipeStatus, LoginFlowV2, MarkAllItemsRead, MarkFeedRead, MarkFolderRead, MarkItem, MarkMultipleItems, MoveFeed, PostWipeSuccess, RenameFeed, RenameFolder, StarItem, and StarMultipleItems.

useStorageChanged

void useStorageChanged ( bool useStorage )

signal

Notifier signal for the useStorage property.

See also

setUseStorage(), isUseStorageEnabled()

wipeManager()

WipeManager * wipeManager

(

)

const

Getter function for the wipeManager property.

See also

setWipeManager(), wipeManagerChanged()

wipeManagerChanged

void wipeManagerChanged ( Fuoten::WipeManager * wipeManager )

signal

Notifier signal for the wipeManager property.

See also

setWipeManager(), wipeManager()