Standard message of network I/O. More...

#include <Invoke.hpp>

Collaboration diagram for samchon::protocol::Invoke:

Public Member Functions
	Invoke ()
	Default Constructor. More...

	Invoke (const std::string &listener)
	Construct from a listener. More...

virtual void	construct (std::shared_ptr< library::XML >) override
	Construct data of the Entity from an XML object. More...

template<typename T , typename... _Args>
	Invoke (const std::string &listener, const T &val, const _Args &...args)
	Construct from arguments. More...

auto	getListener () const -> std::string
	Get listener. More...

void	setListener (const std::string &)
	Set listener. More...

virtual auto	TAG () const -> std::string override
	A tag name when represented by XML. More...

virtual auto	CHILD_TAG () const -> std::string override
	A tag name of children. More...

virtual auto	toXML () const -> std::shared_ptr< library::XML > override
	Get an XML object represents the EntityGroup. More...

auto	toSQL () const -> std::string
	Get a string of sql statement used to archive history log. More...

Public Member Functions inherited from samchon::protocol::EntityGroup< _Container, _ETy, T >
	EntityGroup ()
	Default Constructor. More...

auto	has (const std::string &key) const -> bool
	Indicates whether a container has an object having the specified identifier. More...

auto	get (const std::string &key) -> value_type &
	Access the element by specified identifier(key). More...

auto	get (const std::string &key) const -> const value_type &
	Access the const element by specified identifier(key). More...

Public Member Functions inherited from samchon::protocol::Entity
	Entity ()
	Default Constructor. More...

virtual auto	key () const -> std::string
	Get a key that can identify the Entity uniquely. More...

Public Member Functions inherited from samchon::protocol::IEntityGroup
	IEntityGroup ()
	Default Constructor. More...

Protected Member Functions
virtual auto	createChild (std::shared_ptr< library::XML >) -> InvokeParameter *override
	Factory method of a child Entity. More...

Protected Attributes
std::string	listener
	Represent who listens, often be a function name. More...

Detailed Description

Standard message of network I/O.

Invoke is a class used in network I/O in protocol package of Samchon Framework.

The Invoke message has an XML structure like the result screen of provided example in below. We can enjoy lots of benefits by the normalized and standardized message structure used in network I/O.

The greatest advantage is that we can make any type of network system, even how the system is enourmously complicated. As network communication message is standardized, we only need to concentrate on logical relationships between network systems. We can handle each network system like a object (class) in OOD. And those relationships can be easily designed by using design pattern.

In Samchon Framework, you can make any type of network system with basic 3 + 1 componenets (IProtocol, IServer and IClient + ServerConnector), by implemens or inherits them, like designing classes of S/W architecture.

Example Sources

[Inherited]

Template Parameters

_Container	A type of container containing children entity objects.
_Ety	A type of children entity. It must be a class derived from an Entity class, or Entity class itself.
_Ty	A type of children element of _Container. Using default template parameter is recommended.

EntityGroup is a template class for containinig children Entity objects, and also another type of an Entity, too. You can realize hierarchical relationship. Although some entities have complicated hierarchical relationship, you can deduct a optimal solution easily with EntityGroup and Entity.

If an entity has some subordinate entities of same type, they are in "Composite relationship". Make the entity to be EmntityGroup and subordinate entities to be children of the entity. When those relationships are continued, continue to create classes dervied from EntityGroup. When those relationshiop meets a terminal node, then make the terminal node to be an Entity.

EntityGroup is an Entity, and a container of children Entity objects at the same time. If children type, of a class derived from an EntityGroup, is itself, you can realize hierarchical and recursive relationship. The relationship is called as "Composite pattern".

FTFolder extends FTInstance and SharedEntityArray<FTInstance>
NTCriteria extends SharedEntityArray<NTCriteria>

Note

As a freelancer developer and architect I am, I even design DB I/O to follow the format representing Entity and EntityGroup by XML. Below T-SQL script also follows the standard format of expressing Entity with XML by procedure and "FOR XML AUTO" statement.

 SET 
   ANSI_NULLS, 
   QUOTED_IDENTIFIER, 
   CONCAT_NULL_YIELDS_NULL, 
   ANSI_WARNINGS, 
   ANSI_PADDING 
 ON;
 
 USE OraQ;
 IF OBJECT_ID('v_studyStatus') IS NOT NULL          DROP VIEW v_studyStatus;
 IF OBJECT_ID('v_nonDicomFileStatus') IS NOT NULL   DROP VIEW v_nonDicomFileStatus;
 IF OBJECT_ID('v_candidateStudy') IS NOT NULL       DROP VIEW v_candidateStudy;
 IF OBJECT_ID('v_candidateFile') IS NOT NULL            DROP VIEW v_candidateFile;
 IF OBJECT_ID('goCandidateInspectList') IS NOT NULL DROP PROCEDURE goCandidateInspectList;
 GO
 
 CREATE VIEW v_studyStatus
 AS
    WITH cte AS
    (
        SELECT S.studyUID uid, S.type type, ROW_NUMBER() OVER (PARTITION BY S.studyUID ORDER BY H.datetime DESC) no
        FROM History.history H, History.study S
        WHERE
            H.uid = S.uid AND type <> 1
    )
    SELECT 
        A.uid, 
        CASE WHEN B.type IS NULL THEN
            A.type
            ELSE 1
        END status
    FROM
    (
        SELECT uid, type
        FROM cte
        WHERE no = 1
    ) A LEFT OUTER JOIN
    (
        SELECT studyUID uid, 1 type
        FROM History.study
        GROUP BY studyUID
        HAVING MAX(type) = 1
    ) B ON A.uid = B.uid
 GO
 CREATE VIEW v_nonDicomFileStatus
 AS
    WITH cte AS
    (
        SELECT
            F.fileUID uid, F.type type, 
            ROW_NUMBER() OVER (PARTITION BY F.fileUID ORDER BY H.datetime DESC) no
        FROM History.history H, History.nonDicomFile F
        WHERE
            H.uid = F.uid AND type <> 1
    )
    SELECT 
        A.uid, 
        CASE WHEN B.type IS NULL THEN
            A.type
            ELSE 1
        END status
    FROM
    (
        SELECT uid, type
        FROM cte
        WHERE no = 1
    ) A LEFT OUTER JOIN
    (
        SELECT fileUID uid, 1 type
        FROM History.nonDicomFile
        GROUP BY fileUID
        HAVING MAX(type) = 1
    ) B ON A.uid = B.uid
 GO
 CREATE VIEW v_candidateStudy
 AS
    SELECT DISTINCT
        P.id patientID, 
            P.name patientName, P.gender patientGender, 
            CAST(P.birthdate AS DATE) patientBirthdate,
        S.uid, 
            S.description, 
            CONVERT(VARCHAR, CAST(S.datetime AS DATETIME), 120) AS datetime,
            H.status
    FROM
        Hospital.patient P, Inspect.media M, Inspect.mediaStudyPair A, 
        Inspect.study S, v_studyStatus H
    WHERE
        P.id = M.patientID AND M.uid = A.mediaUID AND A.studyUID = S.uid AND 
        S.uid = H.uid
 GO
 CREATE VIEW v_candidateFile
 AS
    SELECT DISTINCT
        P.id patientID, 
            P.name patientName, P.gender patientGender, 
            CAST(P.birthdate AS DATE) patientBirthdate,
        M.uid mediaUID, 
            F.uid, F.name, F.extension, 
            CONVERT(VARCHAR, CAST(F.datetime AS DATETIME), 120) AS datetime,
            H.status
    FROM 
        Hospital.patient P, Inspect.media M, 
        Inspect.nonDicomFile F, v_nonDicomFileStatus H
    WHERE 
        P.id = M.patientID AND M.uid = F.mediaUID AND F.uid = H.uid
 GO
 
 CREATE PROCEDURE goCandidateInspectList
 AS
    DECLARE @xml XML =
    (
        SELECT *
        FROM
        (
            SELECT N'candidate' service
        ) inspect
        FOR XML AUTO
    )
    DECLARE @studyList XML =
    (
        SELECT study.*, series.*, image.*
        FROM
            v_candidateStudy study 
                LEFT OUTER JOIN Inspect.series series 
                    ON study.uid = series.studyUID
                LEFT OUTER JOIN Inspect.image image
                    ON series.uid = image.seriesUID
        FOR XML AUTO, ROOT(N'studyList')
    )
    DECLARE @fileList XML =
    (
        SELECT * FROM v_candidateFile
        FOR XML RAW(N'file'), ROOT(N'fileList')
    )
 
    IF(@studyList IS NOT NULL)  SET @xml.modify('insert sql:variable("@studyList") into (/inspect)[1]')
    IF(@fileList IS NOT NULL)   SET @xml.modify('insert sql:variable("@fileList") into (/inspect)[1]')
 
    SELECT @xml;
 GO

Warning

EntityGroup contains children entity elements as type of pointer. Because children entity objects are not serialized and referenced by pointer, its iteration and accessment is not fast. If it needs higher performance, then use EntityArray (static array for children entity) instead.

[Inherited]

Entity is a class for standardization of expression method using on network I/O by XML. If Invoke is a standard message protocol of Samchon Framework which must be kept, Entity is a recommended semi-protocol of message for expressing a data class. Following the semi-protocol Entity is not imposed but encouraged.

As we could get advantages from standardization of message for network I/O with Invoke, we can get additional advantage from standardizing expression method of data class with Entity. We do not need to know a part of network communication. Thus, with the Entity, we can only concentrate on entity's own logics and relationships between another entities. Entity does not need to how network communications are being done.

Example Sources

Note

I say repeatedly. Expression method of Entity is recommended, but not imposed. It's a semi protocol for network I/O but not a essential protocol must be kept. The expression method of Entity, using on network I/O, is expressed by XML string.

If your own network system has a critical performance issue on communication data class, it would be better to using binary communication (with ByteArray or boost::serialization). Don't worry about the problem! Invoke also provides methods for binary data (ByteArray).

See also: protocol

Author: Jeongho Nam http://samchon.org

See also: protocol::IProtocol; protocol::InvokeParameter; samchon::protocol

Author: Jeongho Nam http://samchon.org

Definition at line 47 of file Invoke.hpp.

Constructor & Destructor Documentation

Invoke::Invoke ( )

Default Constructor.

Definition at line 14 of file Invoke.cpp.

Invoke::Invoke ( const std::string & listener )

Construct from a listener.

Parameters

listener Represents who listens the Invoke message. Almost same with Function name

Definition at line 18 of file Invoke.cpp.

References listener.

template<typename T , typename... _Args>

samchon::protocol::Invoke::Invoke	(	const std::string &	listener,
		const T &	val,
		const _Args &...	args
	)

inline

Construct from arguments.

Template Parameters

_Ty	Type of an argument which represents a parameter
_Args	Left varadic template arguments' types

Creates Invoke and InvokeParameter(s) at the same time by varadic template method.

By the varadic template constructor, you can't specify name of each InvokeParameter, but specify type and value of each InvokeParameter. If you try to record the Invoke to Database, the name of InvokeParameter will be NULL.

Note

By the varadic template constructor, name of InovkeParameter(s) will be omitted. Because of name, an identifier of an InvokeParameter, is omitted, you can't access to InvokeParameter by Invoke::has() or Invoke::get().

Parameters

listener	A string represents who listens the Invoke message. Almost same with name of a function.
val	A value to be a parameter of Invoke
args	Left arguments to be parameters of Invoke

Definition at line 108 of file Invoke.hpp.

Member Function Documentation

void Invoke::construct ( std::shared_ptr< library::XML > xml )

overridevirtual

Construct data of the Entity from an XML object.

Constructs the EntityGroup's own member variables only from the input XML object.

Do not consider about constructing children Entity objects' data in EntityGroup::construct(). Those children Entity objects' data will constructed by their own construct() method. Even insertion of XML objects representing children are done by abstract method of EntityGroup::toXML().

Constructs only data of EntityGroup's own.

[Inherited]: Construct data of the Entity from an XML object.

Overrides the construct() method and fetch data of member variables from the XML.

By recommended guidance, data representing member variables are contained in properties of the put XML object.

Parameters

xml	An xml used to construct data of entity

Reimplemented from samchon::protocol::EntityGroup< _Container, _ETy, T >.

Definition at line 24 of file Invoke.cpp.

References samchon::protocol::EntityGroup< _Container, _ETy, T >::construct(), and listener.

Here is the call graph for this function:

auto Invoke::createChild ( std::shared_ptr< library::XML > ) -> InvokeParameter *override

overrideprotectedvirtual

Factory method of a child Entity.

EntityGroup::createChild() is a factory method creating a new child Entity which is belonged to the EntityGroup. This method is called by EntityGroup::construct(). The children construction methods Entity::construct() will be called by abstract method of the EntityGroup::construct().

Returns: A new child Entity belongs to EntityGroup.

Implements samchon::protocol::EntityGroup< _Container, _ETy, T >.

Definition at line 30 of file Invoke.cpp.

auto Invoke::getListener ( ) const -> std::string

Get listener.

Definition at line 65 of file Invoke.cpp.

References listener.

void Invoke::setListener ( const std::string & )

Set listener.

Definition at line 70 of file Invoke.cpp.

References listener.

auto Invoke::TAG ( ) const -> std::string

overridevirtual

A tag name when represented by XML.

Returns: A tag name

Implements samchon::protocol::Entity.

Definition at line 78 of file Invoke.cpp.

auto Invoke::CHILD_TAG ( ) const -> std::string

overridevirtual

A tag name of children.

< TAG>
<CHILD_TAG />
<CHILD_TAG />
</TAG>

Implements samchon::protocol::IEntityGroup.

Definition at line 82 of file Invoke.cpp.

auto Invoke::toXML ( ) const -> std::shared_ptr<library::XML>

overridevirtual

Get an XML object represents the EntityGroup.

Archives the EntityGroup's own member variables only to the returned XML object.

Do not consider about archiving children Entity objects' data in EntityGroup::toXML(). Those children Entity objects will converted to XML object by their own toXML() method. The insertion of XML objects representing children are done by abstract method of EntityGroup::toXML().

Archives only data of EntityGroup's own.

[Inherited]: Get an XML object represents the Entity.

Returns an XML object that can represents the Entity containing member variables into properties.

A member variable (not object, but atomic value like number, string or date) is categorized as a property within the framework of entity side. Thus, when overriding a toXML() method and archiving member variables to an XML object to return, puts each variable to be a property belongs to only an XML object.

Don't archive the member variable of atomic value to XML::value causing enormouse creation of XML objects to number of member variables. An Entity must be represented by only an XML instance (tag).

Standard Usage	Non-standard usage abusing value
<memberList> <member id='jhnam88' name='Jeongho+Nam' birthdate='1988-03-11' /> <member id='master' name='Administartor' birthdate='2011-07-28' /> </memberList>	<member> <id>jhnam88</id> <name>Jeongho+Nam</name> <birthdate>1988-03-11</birthdate> </member>