diff --git a/samchon-collection/samchon-collection.d.ts b/samchon-collection/samchon-collection.d.ts index 0bff8791f9..3041c6a618 100644 --- a/samchon-collection/samchon-collection.d.ts +++ b/samchon-collection/samchon-collection.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Samchon Collection v0.0.2 +// Type definitions for Samchon Collection v0.0.4 // Project: https://github.com/samchon/framework // Definitions by: Jeongho Nam // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -7,7 +7,7 @@ declare module "samchon-collection" { - import collection = samchon.collection; - export = collection; + import collections = samchon.collections; + export = collections; } diff --git a/samchon-framework/samchon-framework.d.ts b/samchon-framework/samchon-framework.d.ts index 70d9dda38f..d04ed7fcf3 100644 --- a/samchon-framework/samchon-framework.d.ts +++ b/samchon-framework/samchon-framework.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Samchon Framework v2.0.0-beta.8 +// Type definitions for Samchon Framework v2.0.0-gamma.3 // Project: https://github.com/samchon/framework // Definitions by: Jeongho Nam // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -7,63 +7,110 @@ declare module "samchon-framework" { - export = samchon; + export = samchon; } /** *

Samchon-Framework

* - *

- *

+ * + * * - *

Samchon, a SDN (Software Defined Network) framework.

+ * Samchon, a SDN (Software Defined Network) framework. * - *

With Samchon Framework, you can implement distributed processing system within framework of OOD like - * handling S/W objects (classes). You can realize cloud and distributed system very easily with provided - * system templates and even integration with C++ is possible.

+ * With Samchon Framework, you can implement distributed processing system within framework of OOD like handling S/W + * objects (classes). You can realize cloud and distributed system very easily with provided system templates and even + * integration with C++ is possible. * - *

The goal, ultimate utilization model of Samchon Framework is, building cloud system with NodeJS and - * takING heavy works to C++ distributed systems with provided modules (those are system templates).

+ * The goal, ultimate utilization model of Samchon Framework is, building cloud system with NodeJS and taking heavy works + * to C++ distributed systems with provided modules (those are system templates). * * @git https://github.com/samchon/framework * @author Jeongho Nam */ declare namespace samchon { /** - *

Running on Node.

+ * Running on Node. * - *

Test whether the JavaScript is running on Node.

+ * Test whether the JavaScript is running on Node. * * @references http://stackoverflow.com/questions/17575790/environment-detection-node-js-or-browser */ function is_node(): boolean; } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link Vector} who can detect element I/O events. * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • {@link push_back}
      • - *
    • {@link unshift}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • {@link pop_back}
      • - *
    • {@link shift}
      • - *
    • {@link pop}
      • - *
    • {@link splice}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link sort}
      • - *
    • - *
+ * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - {@link push_back} + * - {@link unshift} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link pop_back} + * - {@link shift} + * - {@link pop} + * - {@link splice} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link Vector} + * {@link Vector Vectors}s are sequence containers representing arrays that can change in size. + * + * Just like arrays, {@link Vector}s use contiguous storage locations for their elements, which means that their + * elements can also be accessed using offsets on regular pointers to its elements, and just as efficiently as in + * arrays. But unlike arrays, their size can change dynamically, with their storage being handled automatically + * by the container. + * + * Internally, {@link Vector}s use a dynamically allocated array to store their elements. This array may need to + * be reallocated in order to grow in size when new elements are inserted, which implies allocating a new array + * and moving all elements to it. This is a relatively expensive task in terms of processing time, and thus, + * {@link Vector}s do not reallocate each time an element is added to the container. + * + * Instead, {@link Vector} containers may allocate some extra storage to accommodate for possible growth, and + * thus the container may have an actual {@link capacity} greater than the storage strictly needed to contain its + * elements (i.e., its {@link size}). Libraries can implement different strategies for growth to balance between + * memory usage and reallocations, but in any case, reallocations should only happen at logarithmically growing + * intervals of {@link size} so that the insertion of individual elements at the end of the {@link Vector} can be + * provided with amortized constant time complexity (see {@link push_back push_back()}). + * + * Therefore, compared to arrays, {@link Vector}s consume more memory in exchange for the ability to manage + * storage and grow dynamically in an efficient way. + * + * Compared to the other dynamic sequence containers ({@link Deque}s, {@link List}s), {@link Vector Vectors} are + * very efficient accessing its elements (just like arrays) and relatively efficient adding or removing elements + * from its end. For operations that involve inserting or removing elements at positions other than the end, they + * perform worse than the others, and have less consistent iterators and references than {@link List}s. + * + * + * + * + * + *

Container properties

+ *
+ *
Sequence
+ *
+ * Elements in sequence containers are ordered in a strict linear sequence. Individual elements are + * accessed by their position in this sequence. + *
+ * + *
Dynamic array
+ *
+ * Allows direct access to any element in the sequence, even through pointer arithmetics, and provides + * relatively fast addition/removal of elements at the end of the sequence. + *
+ *
+ * + * @param Type of the elements. + * + * @reference http://www.cplusplus.com/reference/vector/vector + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class ArrayCollection extends std.Vector implements ICollection { @@ -74,7 +121,7 @@ declare namespace samchon.collection { /** * @inheritdoc */ - push(...items: U[]): number; + push(...items: T[]): number; /** * @inheritdoc */ @@ -170,6 +217,7 @@ declare namespace samchon.library { * A basic event class of Samchon Framework. * * @reference https://developer.mozilla.org/en-US/docs/Web/API/Event + * @handbook https://github.com/samchon/framework/wiki/TypeScript-Library-EventDispatcher * @author Jeongho Nam */ class BasicEvent { @@ -248,48 +296,57 @@ declare namespace samchon.library { returnValue: boolean; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * Type of function pointer for listener of {@link CollectionEvent CollectionEvents}. */ type CollectionEventListener = (event: CollectionEvent) => void; } -declare namespace samchon.collection { +declare namespace samchon.collections { /** + * An event occured in a {@link ICollection collection} object. + * + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class CollectionEvent extends library.BasicEvent { /** * @hidden */ - protected first_: std.Iterator; + private first_; + /** + * @hidden + */ + private last_; /** * @hidden */ - protected last_: std.Iterator; private temporary_container_; + /** + * @hidden + */ private origin_first_; /** * Initialization Constructor. * * @param type Type of collection event. - * @param first - * @param last + * @param first An {@link Iterator} to the initial position in this {@link CollectionEvent}. + * @param last An {@link Iterator} to the final position in this {@link CollectionEvent}. */ constructor(type: string, first: std.Iterator, last: std.Iterator); constructor(type: "insert", first: std.Iterator, last: std.Iterator); constructor(type: "erase", first: std.Iterator, last: std.Iterator); constructor(type: "refresh", first: std.Iterator, last: std.Iterator); /** - * Get associative target, the container. + * Associative target, the {@link ICollection collection}. */ target: ICollection; /** - * Get range of the first. + * An {@link Iterator} to the initial position in this {@link CollectionEvent}. */ first: std.Iterator; /** - * Get range of the last. + * An {@link Iterator} to the final position in this {@link CollectionEvent}. */ last: std.Iterator; /** @@ -301,34 +358,78 @@ declare namespace samchon.collection { /** * @hidden */ -declare namespace samchon.collection.CollectionEvent { +declare namespace samchon.collections.CollectionEvent { const INSERT: "insert"; const ERASE: "erase"; const REFRESH: "refresh"; } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link Deque} who can detect element I/O events. * - *

Below are list of methods who are dispatching {@link CollectionEvent}:

+ * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - {@link push_front} + * - {@link push_back} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link pop_front} + * - {@link pop_back} + * - *refresh* typed events: + * - {@link refresh} * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • {@link push_front}
      • - *
    • {@link push_back}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • {@link pop_front}
      • - *
    • {@link pop_back}
      • - *
    • - *
+ * #### [Inherited] {@link Deque} + * {@link Deque} (usually pronounced like "*deck*") is an irregular acronym of **d**ouble-**e**nded **q**ueue. + * Double-ended queues are sequence containers with dynamic sizes that can be expanded or contracted on both ends + * (either its front or its back). * + * Specific libraries may implement deques in different ways, generally as some form of dynamic array. But in any + * case, they allow for the individual elements to be accessed directly through random access iterators, with + * storage handled automatically by expanding and contracting the container as needed. + * + * Therefore, they provide a functionality similar to vectors, but with efficient insertion and deletion of + * elements also at the beginning of the sequence, and not only at its end. But, unlike {@link Vector Vectors}, + * {@link Deque Deques} are not guaranteed to store all its elements in contiguous storage locations: accessing + * elements in a deque by offsetting a pointer to another element causes undefined behavior. + * + * Both {@link Vector}s and {@link Deque}s provide a very similar interface and can be used for similar purposes, + * but internally both work in quite different ways: While {@link Vector}s use a single array that needs to be + * occasionally reallocated for growth, the elements of a {@link Deque} can be scattered in different chunks of + * storage, with the container keeping the necessary information internally to provide direct access to any of its + * elements in constant time and with a uniform sequential interface (through iterators). Therefore, + * {@link Deque Deques} are a little more complex internally than {@link Vector}s, but this allows them to grow + * more efficiently under certain circumstances, especially with very long sequences, where reallocations become + * more expensive. + * + * For operations that involve frequent insertion or removals of elements at positions other than the beginning or + * the end, {@link Deque Deques} perform worse and have less consistent iterators and references than + * {@link List Lists}. + * + * + * + * + * + *

Container properties

+ *
+ *
Sequence
+ *
Elements in sequence containers are ordered in a strict linear sequence. Individual elements + * are accessed by their position in this sequence.
+ * + *
Dynamic array
+ *
Generally implemented as a dynamic array, it allows direct access to any element in the + * sequence and provides relatively fast addition/removal of elements at the beginning or the end + * of the sequence.
+ *
+ * + * @param Type of the elements. + * + * @reference http://www.cplusplus.com/reference/deque/deque/ + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class DequeCollection extends std.Deque implements ICollection { @@ -339,7 +440,7 @@ declare namespace samchon.collection { /** * @inheritdoc */ - push(...items: U[]): number; + push(...items: T[]): number; /** * @inheritdoc */ @@ -418,30 +519,72 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link HashMap} who can detect element I/O events. * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • {@link set}
      • - *
    • {@link insert_or_assign}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • {@link extract}
      • - *
    • - *
  • refresh typed events:
      - *
    • {@link set}
      • - *
    • {@link insert_or_assign}
      • - *
    • - *
+ * Below is the list of methods who are dispatching {@link MapCollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link insert_or_assign} + * - {@link emplace} + * - {@link set} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link extract} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link HashMap} + * {@link HashMap HashMaps} are associative containers that store elements formed by the combination of a + * *key value* and a *mapped value*, and which allows for fast retrieval of individual elements based on their + * *keys*. + * + * In an {@link HashMap}, the *key value* is generally used to uniquely identify the element, while the + * *mapped value* is an object with the content associated to this *key*. Types of *key* and *mapped value* may + * differ. + * + * Internally, the elements in the {@link HashMap} are not sorted in any particular order with respect to either + * their *key* or *mapped values*, but organized into *buckets* depending on their hash values to allow for fast + * access to individual elements directly by their *key values* (with a constant average time complexity on + * average). + * + * {@link HashMap} containers are faster than {@link TreeMap} containers to access individual elements by their + * *key*, although they are generally less efficient for range iteration through a subset of their elements. + * + * + * + * + * + *

Container properties

+ *
+ *
Associative
+ *
Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container.
+ * + *
Hashed
+ *
Hashed containers organize their elements using hash tables that allow for fast access to elements + * by their *key*.
+ * + *
Map
+ *
Each element associates a *key* to a *mapped value*: + * *Keys* are meant to identify the elements whose main content is the *mapped value*.
+ * + *
Unique keys
+ *
No two elements in the container can have equivalent keys.
+ *
+ * + * @param Type of the key values. + * Each element in an {@link HashMap} is uniquely identified by its key value. + * @param Type of the mapped value. + * Each element in an {@link HashMap} is used to store some data as its mapped value. + * + * @reference http://www.cplusplus.com/reference/unordered_map/unordered_map + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class HashMapCollection extends std.HashMap implements ICollection> { @@ -507,23 +650,69 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: MapCollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link HashMultiMap} who can detect element I/O events. * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • - *
+ * Below is the list of methods who are dispatching {@link MapCollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link emplace} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link HashMultiMap} + * {@link HashMultiMap HashMultiMap}s are associative containers that store elements formed by the combination of + * a *key value* and a *mapped value*, much like {@link HashMultiMap} containers, but allowing different elements + * to have equivalent *keys*. + * + * In an {@link HashMultiMap}, the *key value* is generally used to uniquely identify the element, while the + * *mapped value* is an object with the content associated to this *key*. Types of *key* and *mapped value* may + * differ. + * + * Internally, the elements in the {@link HashMultiMap} are not sorted in any particular order with respect to + * either their *key* or *mapped values*, but organized into *buckets* depending on their hash values to allow for + * fast access to individual elements directly by their *key values* (with a constant average time complexity on + * average). + * + * Elements with equivalent *keys* are grouped together in the same bucket and in such a way that an iterator can + * iterate through all of them. Iterators in the container are doubly linked iterators. + * + * + * + * + * + *

Container properties

+ *
+ *
Associative
+ *
Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container.
+ * + *
Hashed
+ *
Hashed containers organize their elements using hash tables that allow for fast access to elements + * by their *key*.
+ * + *
Map
+ *
Each element associates a *key* to a *mapped value*: + * *Keys* are meant to identify the elements whose main content is the *mapped value*.
+ * + *
Multiple equivalent keys
+ *
The container can hold multiple elements with equivalent *keys*.
+ *
+ * + * @param Type of the key values. + * Each element in an {@link HashMultiMap} is identified by a key value. + * @param Type of the mapped value. + * Each element in an {@link HashMultiMap} is used to store some data as its mapped value. + * + * @reference http://www.cplusplus.com/reference/unordered_map/unordered_multimap + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class HashMultiMapCollection extends std.HashMap implements ICollection> { @@ -589,23 +778,64 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: MapCollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link HashMultiSet} who can detect element I/O events. * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • - *
+ * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link HashMultiSet} + * {@link HashMultiSet HashMultiSets} are containers that store elements in no particular order, allowing fast + * retrieval of individual elements based on their value, much like {@link HashMultiSet} containers, but allowing + * different elements to have equivalent values. + * + * In an {@link HashMultiSet}, the value of an element is at the same time its *key*, used to identify it. *Keys* + * are immutable, therefore, the elements in an {@link HashMultiSet} cannot be modified once in the container - + * they can be inserted and removed, though. + * + * Internally, the elements in the {@link HashMultiSet} are not sorted in any particular, but organized into + * *buckets* depending on their hash values to allow for fast access to individual elements directly by their + * *values* (with a constant average time complexity on average). + * + * Elements with equivalent values are grouped together in the same bucket and in such a way that an iterator can + * iterate through all of them. Iterators in the container are doubly linked iterators. + * + * + * + * + * + *

Container properties

+ *
+ *
Associative
+ *
Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container.
+ * + *
Hashed
+ *
Hashed containers organize their elements using hash tables that allow for fast access to elements + * by their *key*.
+ * + *
Set
+ *
The value of an element is also the *key* used to identify it.
+ * + *
Multiple equivalent keys
+ *
The container can hold multiple elements with equivalent *keys*.
+ *
+ * + * @param Type of the elements. + * Each element in an {@link UnorderedMultiSet} is also identified by this value.. + * + * @reference http://www.cplusplus.com/reference/unordered_set/unordered_multiset + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class HashMultiSetCollection extends std.HashMultiSet implements ICollection { @@ -671,24 +901,65 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link HashSet} who can detect element I/O events. * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • {@link extract}
      • - *
    • - *
+ * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - {@link insert_or_assign} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link extract} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link HashSet} + * {@link HashSet HashSets} are containers that store unique elements in no particular order, and which allow for + * fast retrieval of individual elements based on their value. + * + * In an {@link HashSet}, the value of an element is at the same time its *key*, that identifies it uniquely. + * Keys are immutable, therefore, the elements in an {@link HashSet} cannot be modified once in the container - + * they can be inserted and removed, though. + * + * Internally, the elements in the {@link HashSet} are not sorted in any particular order, but organized into + * buckets depending on their hash values to allow for fast access to individual elements directly by their + * *values* (with a constant average time complexity on average). + * + * {@link HashSet} containers are faster than {@link TreeSet} containers to access individual elements by their + * *key*, although they are generally less efficient for range iteration through a subset of their elements. + * + * + * + * + * + *

Container properties

+ *
+ *
Associative
+ *
Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container.
+ * + *
Hashed
+ *
Hashed containers organize their elements using hash tables that allow for fast access to elements + * by their *key*.
+ * + *
Set
+ *
The value of an element is also the *key* used to identify it.
+ * + *
Unique keys
+ *
No two elements in the container can have equivalent *keys*.
+ *
+ * + * @param Type of the elements. + * Each element in an {@link HashSet} is also uniquely identified by this value. + * + * @reference http://www.cplusplus.com/reference/unordered_set/unordered_set + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class HashSetCollection extends std.HashSet implements ICollection { @@ -754,75 +1025,73 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * An interface for {@link IContainer containers} who can detect element I/O events. * - *

Below are list of methods who are dispatching {@link CollectionEvent}:

- * - *
    - *
  • insert typed events:
      - *
    • {@link assign}
      • - *
    • {@link insert}
      • - *
    • {@link push}
      • - *
    • - *
  • erase typed events:
      - *
    • {@link assign}
      • - *
    • {@link clear}
      • - *
    • {@link erase}
      • - *
    • + * Below are list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - *refresh* typed events: + * - {@link refresh} * * @author Jeongho Nam */ interface ICollection extends std.base.IContainer, library.IEventDispatcher { /** - *

    Dispatch a {@link CollectionEvent} with refresh typed.

    + * Dispatch a {@link CollectionEvent} with *refresh* typed. * - *

    {@link ICollection} dispatches {@link CollectionEvent} typed insert or erase whenever - * elements I/O has occured. However, unlike those elements I/O events, content change in element level can't be - * detected. There's no way to detect those events automatically by {@link IContainer}.

    + * {@link ICollection} dispatches {@link CollectionEvent} typed *insert* or *erase* whenever elements I/O has + * occured. However, unlike those elements I/O events, content change in element level can't be detected. + * There's no way to detect those events automatically by {@link IContainer}. * - *

    If you want to dispatch those typed events (notifying change on contents in element level), you've to - * dispatch refresh typed event manually, by yourself. Call {@link refresh refresh()} with specified + * If you want to dispatch those typed events (notifying change on contents in element level), you've to + * dispatch *refresh* typed event manually, by yourself. Call {@link refresh refresh()} with specified * iterators who're pointing the elements whose content have changed. Then a {@link CollectionEvent} with - * refresh typed will be dispatched.

    + * *refresh* typed will be dispatched. * - *

    If you don't specify any iterator, then the range of the refresh event will be all elements in this - * {@link ICollection collection}; {@link begin begin()} to {@link end end()}.

    + * If you don't specify any iterator, then the range of the *refresh* event will be all elements in this + * {@link ICollection collection}; {@link begin begin()} to {@link end end()}. */ refresh(): void; /** - *

    Dispatch a {@link CollectionEvent} with refresh typed.

    + * Dispatch a {@link CollectionEvent} with *refresh* typed. * - *

    {@link ICollection} dispatches {@link CollectionEvent} typed insert or erase whenever - * elements I/O has occured. However, unlike those elements I/O events, content change in element level can't be - * detected. There's no way to detect those events automatically by {@link IContainer}.

    + * {@link ICollection} dispatches {@link CollectionEvent} typed *insert* or *erase* whenever elements I/O has + * occured. However, unlike those elements I/O events, content change in element level can't be detected. + * There's no way to detect those events automatically by {@link IContainer}. * - *

    If you want to dispatch those typed events (notifying change on contents in element level), you've to - * dispatch refresh typed event manually, by yourself. Call {@link refresh refresh()} with specified + * If you want to dispatch those typed events (notifying change on contents in element level), you've to + * dispatch *refresh* typed event manually, by yourself. Call {@link refresh refresh()} with specified * iterators who're pointing the elements whose content have changed. Then a {@link CollectionEvent} with - * refresh typed will be dispatched.

    + * *refresh* typed will be dispatched. * * @param it An iterator targeting the content changed element. */ refresh(it: std.Iterator): void; /** - *

    Dispatch a {@link CollectionEvent} with refresh typed.

    + * Dispatch a {@link CollectionEvent} with *refresh* typed. * - *

    {@link ICollection} dispatches {@link CollectionEvent} typed insert or erase whenever - * elements I/O has occured. However, unlike those elements I/O events, content change in element level can't be - * detected. There's no way to detect those events automatically by {@link IContainer}.

    + * {@link ICollection} dispatches {@link CollectionEvent} typed *insert* or *erase* whenever elements I/O has + * occured. However, unlike those elements I/O events, content change in element level can't be detected. + * There's no way to detect those events automatically by {@link IContainer}. * - *

    If you want to dispatch those typed events (notifying change on contents in element level), you've to - * dispatch refresh typed event manually, by yourself. Call {@link refresh refresh()} with specified + * If you want to dispatch those typed events (notifying change on contents in element level), you've to + * dispatch *refresh* typed event manually, by yourself. Call {@link refresh refresh()} with specified * iterators who're pointing the elements whose content have changed. Then a {@link CollectionEvent} with - * refresh typed will be dispatched.

    + * *refresh* typed will be dispatched. * * @param first An Iterator to the initial position in a sequence of the content changed elmeents. * @param last An {@link Iterator} to the final position in a sequence of the content changed elements. The range - * used is [first, last), which contains all the elements between first and - * last, including the element pointed by first but not the element pointed by - * last. + * used is [*first*, *last*), which contains all the elements between *first* and + * *last*, including the element pointed by *first* but not the element pointed by + * *last*. */ refresh(first: std.Iterator, last: std.Iterator): void; /** @@ -858,39 +1127,84 @@ declare namespace samchon.collection { * @hidden */ namespace ICollection { + /** + * @hidden + */ function _Dispatch_CollectionEvent(collection: ICollection, type: string, first: std.Iterator, last: std.Iterator): void; + /** + * @hidden + */ function _Dispatch_MapCollectionEvent(collection: ICollection>, type: string, first: std.MapIterator, last: std.MapIterator): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link List} who can detect element I/O events. * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • {@link push_front}
        • - *
      • {@link push_back}
        • - *
      • {@link merge}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • {@link pop_front}
        • - *
      • {@link pop_back}
        • - *
      • {@link unique}
        • - *
      • {@link remove}
        • - *
      • {@link remove_if}
        • - *
      • {@link splice}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link sort}
        • - *
      • - *
    + * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - {@link push_front} + * - {@link push_back} + * - {@link merge} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link pop_front} + * - {@link pop_back} + * - {@link unique} + * - {@link remove} + * - {@link remove_if} + * - {@link splice} + * - *refresh* typed events: + * - {@link refresh} + * - {@link sort} * + * #### [Inherited] {@link List} + * {@link List Lists} are sequence containers that allow constant time insert and erase operations anywhere within + * the sequence, and iteration in both directions. + * + * List containers are implemented as doubly-linked lists; Doubly linked lists can store each of the elements they + * contain in different and unrelated storage locations. The ordering is kept internally by the association to + * each element of a link to the element preceding it and a link to the element following it. + * + * They are very similar to forward_list: The main difference being that forward_list objects are single-linked + * lists, and thus they can only be iterated forwards, in exchange for being somewhat smaller and more efficient. + * + * Compared to other base standard sequence containers (array, vector and deque), lists perform generally better + * in inserting, extracting and moving elements in any position within the container for which an iterator has + * already been obtained, and therefore also in algorithms that make intensive use of these, like sorting + * algorithms. + * + * The main drawback of lists and forward_lists compared to these other sequence containers is that they lack + * direct access to the elements by their position; For example, to access the sixth element in a list, one has to + * iterate from a known position (like the beginning or the end) to that position, which takes linear time in the + * distance between these. They also consume some extra memory to keep the linking information associated to each + * element (which may be an important factor for large lists of small-sized elements). + * + * + * + * + * + *

    Container properties

    + *
    + *
    Sequence
    + *
    Elements in sequence containers are ordered in a strict linear sequence. Individual elements are accessed by + * their position in this sequence.
    + * + *
    Doubly-linked list
    + *
    Each element keeps information on how to locate the next and the previous elements, allowing constant time + * insert and erase operations before or after a specific element (even of entire ranges), but no direct random + * access.
    + *
    + * + * @param Type of the elements. + * + * @reference http://www.cplusplus.com/reference/list/list/ + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class ListCollection extends std.List implements ICollection { @@ -901,7 +1215,7 @@ declare namespace samchon.collection { /** * @inheritdoc */ - push(...items: T[]): number; + push(...items: T[]): number; /** * @inheritdoc */ @@ -988,8 +1302,14 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { type MapCollectionEventListener = (event: MapCollectionEvent) => void; + /** + * An event occured in a {@link MapContainer map container} object. + * + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) + * @author Jeongho Nam + */ class MapCollectionEvent extends CollectionEvent> { /** * @inheritdoc @@ -1001,30 +1321,71 @@ declare namespace samchon.collection { last: std.MapIterator; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link TreeMap} who can detect element I/O events. * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • {@link set}
        • - *
      • {@link insert_or_assign}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • {@link extract}
        • - *
      • - *
    • refresh typed events:
        - *
      • {@link set}
        • - *
      • {@link insert_or_assign}
        • - *
      • - *
    + * Below is the list of methods who are dispatching {@link MapCollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link insert_or_assign} + * - {@link emplace} + * - {@link set} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link extract} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link TreeMap} + * {@link TreeMap TreeMaps} are associative containers that store elements formed by a combination of a + * *key value* (*Key*) and a *mapped value* (*T*), following order. + * + * In a {@link TreeMap}, the *key values* are generally used to sort and uniquely identify the elements, while the + * *mapped values* store the content associated to this key. The types of *key* and *mapped value* may differ, and + * are grouped together in member type *value_type*, which is a {@link Pair} type combining both: + * + * ```typedef Pair value_type;``` + * + * Internally, the elements in a {@link TreeMap} are always sorted by its *key* following a *strict weak ordering* + * criterion indicated by its internal comparison method {@link less}. + * + * {@link TreeMap} containers are generally slower than {@link HashMap HashMap} containers to access individual + * elements by their *key*, but they allow the direct iteration on subsets based on their order. + * + * {@link TreeMap}s are typically implemented as binary search trees. + * + * + * + * + * + *

    Container properties

    + *
    + *
    Associative
    + *
    Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container.
    + * + *
    Ordered
    + *
    The elements in the container follow a strict order at all times. All inserted elements are + * given a position in this order.
    + * + *
    Map
    + *
    Each element associates a *key* to a *mapped value*: + * *Keys* are meant to identify the elements whose main content is the *mapped value*.
    + * + *
    Unique keys
    + *
    No two elements in the container can have equivalent *keys*.
    + *
    + * + * @param Type of the keys. Each element in a map is uniquely identified by its key value. + * @param Type of the mapped value. Each element in a map stores some data as its mapped value. + * + * @reference http://www.cplusplus.com/reference/map/map + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class TreeMapCollection extends std.TreeMap implements ICollection> { @@ -1090,23 +1451,75 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: MapCollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link TreeMultiMap} who can detect element I/O events. * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • - *
    + * Below is the list of methods who are dispatching {@link MapCollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link emplace} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link TreeMultiMap} + * {@link TreeMultiMap TreeMultiMaps} are associative containers that store elements formed by a combination of a + * *key value* and a *mapped value*, following a specific order, and where multiple elements can have equivalent + * keys. + * + * In a {@link TreeMultiMap}, the *key values* are generally used to sort and uniquely identify the elements, + * while the *mapped values* store the content associated to this *key*. The types of *key* and *mapped value* may + * differ, and are grouped together in member type ```value_type```, which is a {@link Pair} type combining both: + * + * ```typedef Pair value_type;``` + * + * Internally, the elements in a {@link TreeMultiMap}are always sorted by its key following a strict weak ordering + * criterion indicated by its internal comparison method (of {@link less}). + * + * {@link TreeMultiMap}containers are generally slower than {@link HashMap} containers to access individual + * elements by their *key*, but they allow the direct iteration on subsets based on their order. + * + * {@link TreeMultiMap TreeMultiMaps} are typically implemented as binary search trees. + * + * < + * img src="http://samchon.github.io/typescript-stl/images/design/class_diagram/map_containers.png" style="max-width: 100%" /> + * + * + *

    Container properties

    + *
    + *
    Associative
    + *
    + * Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container. + *
    + * + *
    Ordered
    + *
    + * The elements in the container follow a strict order at all times. All inserted elements are + * given a position in this order. + *
    + * + *
    Map
    + *
    + * Each element associates a *key* to a *mapped value*: + * *Keys* are meant to identify the elements whose main content is the *mapped value*. + *
    + * + *
    Multiple equivalent keys
    + *
    Multiple elements in the container can have equivalent *keys*.
    + *
    + * + * @param Type of the keys. Each element in a map is uniquely identified by its key value. + * @param Type of the mapped value. Each element in a map stores some data as its mapped value. + * + * @reference http://www.cplusplus.com/reference/map/multimap + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class TreeMultiMapCollection extends std.TreeMultiMap implements ICollection> { @@ -1172,23 +1585,67 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: MapCollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link TreeMultiSet} who can detect element I/O events. * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • - *
    + * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link TreeMultiSet} + * {@link TreeMultiSet TreeMultiSets} are containers that store elements following a specific order, and where + * multiple elements can have equivalent values. + * + * In a {@link TreeMultiSet}, the value of an element also identifies it (the value is itself the *key*, of type + * *T*). The value of the elements in a {@link TreeMultiSet} cannot be modified once in the container (the + * elements are always const), but they can be inserted or removed from the container. + * + * Internally, the elements in a {@link TreeMultiSet TreeMultiSets} are always sorted following a strict weak + * ordering criterion indicated by its internal comparison method (of {@link IComparable.less less}). + * + * {@link TreeMultiSet} containers are generally slower than {@link HashMultiSet} containers to access individual + * elements by their *key*, but they allow the direct iteration on subsets based on their order. + * + *

    {@link TreeMultiSet TreeMultiSets} are typically implemented as binary search trees.

    + * + *

    + *

    + * + *

    Container properties

    + *
    + *
    Associative
    + *
    + * Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container. + *
    + * + *
    Ordered
    + *
    + * The elements in the container follow a strict order at all times. All inserted elements are + * given a position in this order. + *
    + * + *
    Set
    + *
    The value of an element is also the *key* used to identify it.
    + * + *
    Multiple equivalent keys
    + *
    Multiple elements in the container can have equivalent *keys*.
    + *
    + * + * @param Type of the elements. Each element in a {@link TreeMultiSet} container is also identified + * by this value (each value is itself also the element's *key*). + * + * @reference http://www.cplusplus.com/reference/set/multiset + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class TreeMultiSetCollection extends std.TreeMultiSet implements ICollection { @@ -1254,24 +1711,69 @@ declare namespace samchon.collection { removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; } } -declare namespace samchon.collection { +declare namespace samchon.collections { /** * A {@link TreeMap} who can detect element I/O events. * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • {@link extract}
        • - *
      • - *
    + * Below is the list of methods who are dispatching {@link CollectionEvent}: + * - *insert* typed events: + * - {@link assign} + * - {@link insert} + * - {@link insert_or_assign} + * - {@link push} + * - *erase* typed events: + * - {@link assign} + * - {@link clear} + * - {@link erase} + * - {@link extract} + * - *refresh* typed events: + * - {@link refresh} * + * #### [Inherited] {@link TreeSet} + * {@link TreeSet TreeSets} are containers that store unique elements following a specific order. + * + * In a {@link TreeSet}, the value of an element also identifies it (the value is itself the *key*, of type *T*), + * and each value must be unique. The value of the elements in a {@link TreeSet} cannot be modified once in the + * container (the elements are always const), but they can be inserted or removed from the container. + * + * Internally, the elements in a {@link TreeSet} are always sorted following a specific strict weak ordering + * criterion indicated by its internal comparison method (of {@link less}). + * + * {@link TreeSet} containers are generally slower than {@link HashSet} containers to access individual elements + * by their *key*, but they allow the direct iteration on subsets based on their order. + * + * {@link TreeSet}s are typically implemented as binary search trees. + * + * + * + * + * + *

    Container properties

    + *
    + *
    Associative
    + *
    + * Elements in associative containers are referenced by their *key* and not by their absolute + * position in the container. + *
    + * + *
    Ordered
    + *
    + * The elements in the container follow a strict order at all times. All inserted elements are + * given a position in this order. + *
    + * + *
    Set
    + *
    The value of an element is also the *key* used to identify it.
    + * + *
    Unique keys
    + *
    No two elements in the container can have equivalent *keys*.
    + *
    + * + * @param Type of the elements. + * Each element in an {@link TreeSet} is also uniquely identified by this value. + * + * @reference http://www.cplusplus.com/reference/set/set + * @handbook [Collections](https://github.com/samchon/framework/wiki/TypeScript-STL#collections) * @author Jeongho Nam */ class TreeSetCollection extends std.TreeSet implements ICollection { @@ -1339,483 +1841,9 @@ declare namespace samchon.collection { } declare namespace samchon.library { /** - *

    XML is a class representing a tree structued xml objects.

    - *

    The XML class provides methods and properties for working with XML objects.

    + * Case generator. * - *

    The XML class (along with the XMLList and Namespace) implements - * the powerful XML-handling standard defined in ECMAScript for XML (E4X) specification.

    - * - *

    XML class has a recursive, hierarchical relationship.

    - * - *

    Relationships between XML and XMLList

    - *
      - *
    • XML is std.HashMap
      • - *
    • XMLList is std.Deque
      • - *
    - * - *

    Note

    - *

    Do not abuse values for expressing member variables.

    - * - * - * - * - * - * - * - * - * - * - *
    Standard UsageNon-standard usage abusing value
    - * - * - * - * - * - * - * - * - * - * - * jhnam88 - * Jeongho Nam - * 1988-03-11 - * - * - * master - * Administartor - * 2011-07-28 - * - * - * - *
    - * - * @author Jeongho Nam - */ - class XML extends std.HashMap { - /** - *

    Tag name of the XML.

    - * - *
      - *
    • \<tag label='property' /\>: tag => \"tag\"
      • - *
    • \<price high='1500' low='1300' open='1450' close='1320' /\>: tag => \"price\"
      • - *
    - */ - private tag_; - /** - *

    Value of the XML.

    - * - *
      - *
    • \26\: value => 26
      • - *
    • \: value => null
      • - *
    - */ - private value_; - /** - *

    Properties belongs to the XML.

    - *

    A Dictionary of properties accessing each property by its key.

    - * - *
      - *
    • \high='1500' low='1300' open='1450' close='1320' /\>: - * propertyMap => {{\"high\": 1500}, {\"low\": 1300}, {\"open\": 1450}, {\"close\", 1320}}
      • - *
    • \id='jhnam88' name='Jeongho+Nam' comment='Hello.+My+name+is+Jeongho+Nam' \>: - * propertyMap => {{\"id\", \"jhnam88\"}, {\"name\", \"Jeongho Nam \"}, - * {\"comment\", \"Hello. My name is Jeongho Nam \"}}
      • - *
    - */ - private property_map_; - /** - *

    Default Constructor.

    - * - *

    If the string parameter is not omitted, constructs its tag, value and - * properties by parsing the string. If there's children, then construct the - * children XML, XMLList objects, too.

    - * - * @param str A string to be parsed - */ - constructor(str?: string); - /** - *

    Construct XML objects by parsing a string.

    - */ - private construct(str); - /** - *

    Parse and fetch a tag.

    - */ - private parseTag(str); - /** - *

    Parse and fetch properties.

    - */ - private parseProperty(str); - /** - *

    Parse and fetch a value.

    - */ - private parseValue(str); - /** - *

    Parse and construct children XML objects.

    - */ - private parseChildren(str); - /** - *

    Get tag.

    - */ - getTag(): string; - /** - *

    Get value.

    - */ - getValue(): string; - /** - *

    Test whether a property exists or not.

    - */ - hasProperty(key: string): boolean; - /** - *

    Get property by its key.

    - */ - getProperty(key: string): string; - getPropertyMap(): std.HashMap; - /** - *

    Set tag (identifier) of the XML.

    - */ - setTag(str: string): void; - /** - *

    Set value of the XML.

    - * - *

    Do not abuse values for expressing member variables.

    - * - * - * - * - * - * - * - * - * - *
    Standard UsageNon-standard usage abusing value
    - * \\n - *     \\n - *     \\n - * \ - * - * \\n - * \jhnam88\\n - * \Jeongho+Nam\\n - * \1988-03-11\\n - * \ - *
    - * - * @param val A value to set - */ - setValue(str: string): void; - /** - *

    Set a property with its key.

    - */ - setProperty(key: string, value: string): void; - /** - *

    Erase a property by its key.

    - * - * @param key The key of the property to erase - * @throw exception out of range - */ - eraseProperty(key: string): void; - push(...args: std.Pair[]): number; - push(...args: [L, U][]): number; - push(...xmls: XML[]): number; - push(...xmlLists: XMLList[]): number; - addAllProperties(xml: XML): void; - clearProperties(): void; - private calcMinIndex(...args); - /** - *

    Decode a value.

    - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    EncodedDecoded
    \&\&
    \<\<
    \>\>
    - * - * @return A decoded string represents a value - */ - static decodeValue(str: string): string; - /** - *

    Encode a value.

    - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    OriginalEncoded
    \&\&
    \<\<
    \>\>
    - * - * @return A encoded string represents a value - */ - static encodeValue(str: string): string; - /** - *

    Decode a property.

    - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    EncodedDecoded
    \&\&
    \<\<
    \>\>
    "\"
    ''
    '
    '\\t
    \\n
    \\r
    - * - * @return A decoded string represents a property - */ - static decodeProperty(str: string): string; - /** - *

    Decode a property.

    - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    OriginalEncoded
    \&\&
    \<\<
    \>\>
    \""
    ''
    '
    \\t'
    \\n
    \\r
    - * - * @return A encoded string represents a property - */ - static encodeProperty(str: string): string; - /** - *

    Convert the XML to a string.

    - */ - toString(level?: number): string; - /** - *

    Convert the XML to HTML string.

    - */ - toHTML(level?: number): string; - } - /** - *

    List of XML(s) having same tag.

    - * - * @author Jeongho Nam - */ - class XMLList extends std.Deque { - getTag(): string; - /** - *

    Convert XMLList to string.

    - * - * @param level Level(depth) of the XMLList. - */ - toString(level?: number): string; - /** - *

    Convert XMLList to HTML string.

    - * - * @param level Level(depth) of the XMLList. - */ - toHTML(level?: number): string; - } -} -declare namespace samchon.collection { - /** - * An {@link XMLList} who can detect element I/O events. - * - *

    Below are list of methods who are dispatching {@link CollectionEvent}:

    - * - *
      - *
    • insert typed events:
        - *
      • {@link assign}
        • - *
      • {@link insert}
        • - *
      • {@link push}
        • - *
      • {@link push_front}
        • - *
      • {@link push_back}
        • - *
      • - *
    • erase typed events:
        - *
      • {@link assign}
        • - *
      • {@link clear}
        • - *
      • {@link erase}
        • - *
      • {@link pop_front}
        • - *
      • {@link pop_back}
        • - *
      • - *
    - * - * @author Jeongho Nam - */ - class XMLListCollection extends library.XMLList implements ICollection { - /** - * A chain object taking responsibility of dispatching events. - */ - private event_dispatcher_; - /** - * @inheritdoc - */ - push(...items: U[]): number; - /** - * @inheritdoc - */ - push_back(val: library.XML): void; - /** - * @hidden - */ - protected _Insert_by_repeating_val(position: std.DequeIterator, n: number, val: library.XML): std.DequeIterator; - /** - * @hidden - */ - protected _Insert_by_range>(position: std.DequeIterator, begin: InputIterator, end: InputIterator): std.DequeIterator; - /** - * @inheritdoc - */ - pop_back(): void; - /** - * @hidden - */ - protected _Erase_by_range(first: std.DequeIterator, last: std.DequeIterator): std.DequeIterator; - /** - * @hidden - */ - private notify_insert(first, last); - /** - * @hidden - */ - private notify_erase(first, last); - /** - * @inheritdoc - */ - hasEventListener(type: string): boolean; - /** - * @inheritdoc - */ - dispatchEvent(event: library.BasicEvent): boolean; - /** - * @inheritdoc - */ - refresh(): void; - /** - * @inheritdoc - */ - refresh(it: std.DequeIterator): void; - /** - * @inheritdoc - */ - refresh(first: std.DequeIterator, last: std.DequeIterator): void; - /** - * @inheritdoc - */ - addEventListener(type: string, listener: library.BasicEventListener): void; - addEventListener(type: "insert", listener: CollectionEventListener): void; - addEventListener(type: "erase", listener: CollectionEventListener): void; - addEventListener(type: "refresh", listener: CollectionEventListener): void; - /** - * @inheritdoc - */ - addEventListener(type: string, listener: library.BasicEventListener, thisArg: Object): void; - addEventListener(type: "insert", listener: CollectionEventListener, thisArg: Object): void; - addEventListener(type: "erase", listener: CollectionEventListener, thisArg: Object): void; - addEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; - /** - * @inheritdoc - */ - removeEventListener(type: string, listener: library.BasicEventListener): void; - removeEventListener(type: "insert", listener: CollectionEventListener): void; - removeEventListener(type: "erase", listener: CollectionEventListener): void; - removeEventListener(type: "refresh", listener: CollectionEventListener): void; - /** - * @inheritdoc - */ - removeEventListener(type: string, listener: library.BasicEventListener, thisArg: Object): void; - removeEventListener(type: "insert", listener: CollectionEventListener, thisArg: Object): void; - removeEventListener(type: "erase", listener: CollectionEventListener, thisArg: Object): void; - removeEventListener(type: "refresh", listener: CollectionEventListener, thisArg: Object): void; - } -} -declare namespace samchon.library { - /** - *

    Case generator.

    - * - *

    {@link CaseGenerator} is an abstract case generator being used like a matrix.

    + * {@link CaseGenerator} is an abstract case generator being used like a matrix. *
      *
    • n��r(n^r) -> {@link CombinedPermutationGenerator}
      • *
    • nPr -> {@link PermutationGenerator}
      • @@ -1826,40 +1854,40 @@ declare namespace samchon.library { */ abstract class CaseGenerator { /** - *

      Size, the number of all cases.

      + * Size, the number of all cases. */ protected size_: number; /** - *

      N, size of the candidates.

      + * N, size of the candidates. */ protected n_: number; /** - *

      R, size of elements of each case.

      + * R, size of elements of each case. */ protected r_: number; /** - *

      Construct from size of N and R.

      + * Construct from size of N and R. * * @param n Size of candidates. * @param r Size of elements of each case. */ constructor(n: number, r: number); /** - *

      Get size of all cases.

      + * Get size of all cases. * * @return Get a number of the all cases. */ size(): number; /** - *

      Get size of the N.

      + * Get size of the N. */ n(): number; /** - *

      Get size of the R.

      + * Get size of the R. */ r(): number; /** - *

      Get index'th case.

      + * Get index'th case. * * @param index Index number * @return The row of the index'th in combined permuation case @@ -1867,19 +1895,19 @@ declare namespace samchon.library { abstract at(index: number): number[]; } /** - *

      A combined-permutation case generator.

      + * A combined-permutation case generator. * - *

      n��r

      + * n��r * * @author Jeongho Nam */ class CombinedPermutationGenerator extends CaseGenerator { /** - *

      An array using for dividing each element index.

      + * An array using for dividing each element index. */ private divider_array; /** - *

      Construct from size of N and R.

      + * Construct from size of N and R. * * @param n Size of candidates. * @param r Size of elements of each case. @@ -1888,15 +1916,15 @@ declare namespace samchon.library { at(index: number): number[]; } /** - *

      A permutation case generator.

      + * A permutation case generator. * - *

      nPr

      + * nPr * * @author Jeongho Nam */ class PermuationGenerator extends CaseGenerator { /** - *

      Construct from size of N and R.

      + * Construct from size of N and R. * * @param n Size of candidates. * @param r Size of elements of each case. @@ -1908,9 +1936,9 @@ declare namespace samchon.library { at(index: number): number[]; } /** - *

      Factorial case generator.

      + * Factorial case generator. * - *

      n! = nPn

      + * n! = nPn * * @author Jeongho Nam */ @@ -1926,87 +1954,87 @@ declare namespace samchon.library { declare namespace samchon.library { type BasicEventListener = (event: BasicEvent) => void; /** - *

      The IEventDispatcher interface defines methods for adding or removing event listeners, checks - * whether specific types of event listeners are registered, and dispatches events.

      + * The IEventDispatcher interface defines methods for adding or removing event listeners, checks whether specific + * types of event listeners are registered, and dispatches events. * - *

      Event targets are an important part of the Flash�� Player and Adobe AIR event model. The event - * target serves as the local point for how events flow through the display list hierarchy. When an - * event such as a mouse click or a key press occurs, an event object is dispatched into the event flow - * from the root of the display list. The event object makes a round-trip journey to the event target, - * which is conceptually divided into three phases: the capture phase includes the journey from the - * root to the last node before the event target's node; the target phase includes only the event - * target node; and the bubbling phase includes any subsequent nodes encountered on the return trip to - * the root of the display list.

      + * The event target serves as the local point for how events flow through the display list hierarchy. When an + * event such as a mouse click or a key press occurs, an event object is dispatched into the event flow from the + * root of the display list. The event object makes a round-trip journey to the event target, which is + * conceptually divided into three phases: the capture phase includes the journey from the root to the last node + * before the event target's node; the target phase includes only the event target node; and the bubbling phase + * includes any subsequent nodes encountered on the return trip to the root of the display list. * - *

      In general, the easiest way for a user-defined class to gain event dispatching capabilities is - * to extend EventDispatcher. If this is impossible (that is, if the class is already extending another - * class), you can instead implement the IEventDispatcher interface, create an EventDispatcher member, - * and write simple hooks to route calls into the aggregated EventDispatcher.

      + * In general, the easiest way for a user-defined class to gain event dispatching capabilities is to extend + * {@link EventDispatcher}. If this is impossible (that is, if the class is already extending another class), you + * can instead implement the {@link IEventDispatcher} interface, create an {@link EventDispatcher} member, and + * write simple hooks to route calls into the aggregated {@link EventDispatcher}. * * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/IEventDispatcher.html + * @handbook https://github.com/samchon/framework/wiki/TypeScript-Library-EventDispatcher * @author Migrated by Jeongho Nam */ interface IEventDispatcher { /** - *

      Checks whether the EventDispatcher object has any listeners registered for a specific type - * of event. This allows you to determine where an EventDispatcher object has altered handling of - * an event type in the event flow hierarchy. To determine whether a specific event type actually - * triggers an event listener, use willTrigger().

      + * Checks whether the {@link EventDispatcher} object has any listeners registered for a specific type of event. + * This allows you to determine where an {@link EventDispatcher} object has altered handling of an event type + * in the event flow hierarchy. To determine whether a specific event type actually triggers an event listener, + * use {@link willTrigger willTrigger()}. * - *

      The difference between hasEventListener() and willTrigger() is that hasEventListener() - * examines only the object to which it belongs, whereas willTrigger() examines the entire event - * flow for the event specified by the type parameter.

      + * The difference between {@link hasEventListener hasEventListener()} and {@link willTrigger willTrigger()} is + * that {@link hasEventListener} examines only the object to which it belongs, whereas {@link willTrigger} + * examines the entire event flow for the event specified by the type parameter. * * @param type The type of event. */ hasEventListener(type: string): boolean; /** - *

      Dispatches an event into the event flow.

      - *

      The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

      + * Dispatches an event into the event flow. * - * @param event The Event object that is dispatched into the event flow. If the event is being - * redispatched, a clone of the event is created automatically. After an event is - * dispatched, its target property cannot be changed, so you must create a new copy - * of the event for redispatching to work. + * The event target is the {@link EventDispatcher} object upon which the {@link dispatchEvent dispatchEvent()} + * method is called. + * + * @param event The {@link BasicEvent} object that is dispatched into the event flow. If the event is being + * redispatched, a clone of the event is created automatically. After an event is dispatched, its + * target property cannot be changed, so you must create a new copy + * of the event for redispatching to work. */ dispatchEvent(event: library.BasicEvent): boolean; /** - *

      Registers an event listener object with an EventDispatcher object so that the listener - * receives notification of an event. You can register event listeners on all nodes in the display - * list for a specific type of event, phase, and priority. + * Registers an event listener object with an {@link EventDispatcher} object so that the listener receives + * notification of an event. You can register event listeners on all nodes in the display list for a specific + * type of event, phase, and priority. * - *

      After you successfully register an event listener, you cannot change its priority through - * additional calls to addEventListener(). To change a listener's priority, you must first call - * removeEventListener(). Then you can register the listener again with the new priority level.

      + * After you successfully register an event listener, you cannot change its priority through additional calls + * to {@link addEventListener addEventListener()|} To change a listener's priority, you must first call + * {@link removeEventListener removeEventListener()}. Then you can register the listener again with the new + * priority level. * - *

      Keep in mind that after the listener is registered, subsequent calls to addEventListener() - * with a different type or useCapture value result in the creation of a separate listener - * registration. For example, if you first register a listener with useCapture set to true, - * it listens only during the capture phase. If you call addEventListener() again using the same - * listener object, but with useCapture set to false, you have two separate listeners: one that - * listens during the capture phase and another that listens during the target and bubbling phases.

      + * Keep in mind that after the listener is registered, subsequent calls to {@link addEventListener} with a + * different type or useCapture value result in the creation of a separate listener registration. For example, + * if you first register a listener with useCapture set to true, it listens only during the capture phase. If + * you call {@link addEventListener} again using the same listener object, but with useCapture set to false, + * you have two separate listeners: one that listens during the capture phase and another that listens during + * the target and bubbling phases. * - *

      You cannot register an event listener for only the target phase or the bubbling phase. - * Those phases are coupled during registration because bubbling applies only to the ancestors of - * the target node.

      + * You cannot register an event listener for only the target phase or the bubbling phase. Those phases are + * coupled during registration because bubbling applies only to the ancestors of the target node. * - *

      If you no longer need an event listener, remove it by calling removeEventListener(), or - * memory problems could result. Event listeners are not automatically removed from memory because - * the garbage collector does not remove the listener as long as the dispatching object exists - * (unless the useWeakReference parameter is set to true).

      + * If you no longer need an event listener, remove it by calling {@link removeEventListener}, or memory + * problems could result. Event listeners are not automatically removed from memory because the garbage + * collector does not remove the listener as long as the dispatching object exists (unless the + * useWeakReference parameter is set to true). * - *

      Copying an EventDispatcher instance does not copy the event listeners attached to it. (If - * your newly created node needs an event listener, you must attach the listener after creating - * the node.) However, if you move an EventDispatcher instance, the event listeners attached to - * it move along with it.

      + * Copying an {@link EventDispatcher} instance does not copy the event listeners attached to it. (If your n + * ewly created node needs an event listener, you must attach the listener after creating the node.) However, + * if you move an {@link EventDispatcher} instance, the event listeners attached to it move along with it. * - *

      If the event listener is being registered on a node while an event is also being processed - * on this node, the event listener is not triggered during the current phase but may be triggered - * during a later phase in the event flow, such as the bubbling phase.

      + * If the event listener is being registered on a node while an event is also being processed on this node, + * the event listener is not triggered during the current phase but may be triggered during a later phase in + * the event flow, such as the bubbling phase. * - *

      If an event listener is removed from a node while an event is being processed on the node, - * it is still triggered by the current actions. After it is removed, the event listener is never - * invoked again (unless it is registered again for future processing).

      + * If an event listener is removed from a node while an event is being processed on the node, it is still + * triggered by the current actions. After it is removed, the event listener is never invoked again (unless it + * is registered again for future processing). * * @param event The type of event. * @param listener The listener function that processes the event. @@ -2015,121 +2043,97 @@ declare namespace samchon.library { */ addEventListener(type: string, listener: library.BasicEventListener): void; /** - *

      Registers an event listener object with an EventDispatcher object so that the listener - * receives notification of an event. You can register event listeners on all nodes in the display - * list for a specific type of event, phase, and priority. + * Registers an event listener object with an {@link EventDispatcher} object so that the listener receives + * notification of an event. You can register event listeners on all nodes in the display list for a specific + * type of event, phase, and priority. * - *

      After you successfully register an event listener, you cannot change its priority through - * additional calls to addEventListener(). To change a listener's priority, you must first call - * removeEventListener(). Then you can register the listener again with the new priority level.

      + * After you successfully register an event listener, you cannot change its priority through additional calls + * to {@link addEventListener addEventListener()|} To change a listener's priority, you must first call + * {@link removeEventListener removeEventListener()}. Then you can register the listener again with the new + * priority level. * - *

      Keep in mind that after the listener is registered, subsequent calls to addEventListener() - * with a different type or useCapture value result in the creation of a separate listener - * registration. For example, if you first register a listener with useCapture set to true, - * it listens only during the capture phase. If you call addEventListener() again using the same - * listener object, but with useCapture set to false, you have two separate listeners: one that - * listens during the capture phase and another that listens during the target and bubbling phases.

      + * Keep in mind that after the listener is registered, subsequent calls to {@link addEventListener} with a + * different type or useCapture value result in the creation of a separate listener registration. For example, + * if you first register a listener with useCapture set to true, it listens only during the capture phase. If + * you call {@link addEventListener} again using the same listener object, but with useCapture set to false, + * you have two separate listeners: one that listens during the capture phase and another that listens during + * the target and bubbling phases. * - *

      You cannot register an event listener for only the target phase or the bubbling phase. - * Those phases are coupled during registration because bubbling applies only to the ancestors of - * the target node.

      + * You cannot register an event listener for only the target phase or the bubbling phase. Those phases are + * coupled during registration because bubbling applies only to the ancestors of the target node. * - *

      If you no longer need an event listener, remove it by calling removeEventListener(), or - * memory problems could result. Event listeners are not automatically removed from memory because - * the garbage collector does not remove the listener as long as the dispatching object exists - * (unless the useWeakReference parameter is set to true).

      + * If you no longer need an event listener, remove it by calling {@link removeEventListener}, or memory + * problems could result. Event listeners are not automatically removed from memory because the garbage + * collector does not remove the listener as long as the dispatching object exists (unless the + * useWeakReference parameter is set to true). * - *

      Copying an EventDispatcher instance does not copy the event listeners attached to it. (If - * your newly created node needs an event listener, you must attach the listener after creating - * the node.) However, if you move an EventDispatcher instance, the event listeners attached to - * it move along with it.

      + * Copying an {@link EventDispatcher} instance does not copy the event listeners attached to it. (If your n + * ewly created node needs an event listener, you must attach the listener after creating the node.) However, + * if you move an {@link EventDispatcher} instance, the event listeners attached to it move along with it. * - *

      If the event listener is being registered on a node while an event is also being processed - * on this node, the event listener is not triggered during the current phase but may be triggered - * during a later phase in the event flow, such as the bubbling phase.

      + * If the event listener is being registered on a node while an event is also being processed on this node, + * the event listener is not triggered during the current phase but may be triggered during a later phase in + * the event flow, such as the bubbling phase. * - *

      If an event listener is removed from a node while an event is being processed on the node, - * it is still triggered by the current actions. After it is removed, the event listener is never - * invoked again (unless it is registered again for future processing).

      + * If an event listener is removed from a node while an event is being processed on the node, it is still + * triggered by the current actions. After it is removed, the event listener is never invoked again (unless it + * is registered again for future processing). * * @param event The type of event. * @param listener The listener function that processes the event. * This function must accept an Event object as its only parameter and must return * nothing. - * @param thisArg The object to be used as the this object. + * @param thisArg The object to be used as the **this** object. */ addEventListener(type: string, listener: library.BasicEventListener, thisArg: Object): void; /** - * Removes a listener from the EventDispatcher object. If there is no matching listener registered - * with the EventDispatcher object, a call to this method has no effect. + * Removes a listener from the {@link EventDispatcher} object. If there is no matching listener registered + * with the {@link EventDispatcher} object, a call to this method has no effect. * * @param type The type of event. * @param listener The listener object to remove. */ removeEventListener(type: string, listener: library.BasicEventListener): void; /** - * Removes a listener from the EventDispatcher object. If there is no matching listener registered - * with the EventDispatcher object, a call to this method has no effect. + * Removes a listener from the {@link EventDispatcher} object. If there is no matching listener registered + * with the {@link EventDispatcher} object, a call to this method has no effect. * * @param type The type of event. * @param listener The listener object to remove. - * @param thisArg The object to be used as the this object. + * @param thisArg The object to be used as the **this** object. */ removeEventListener(type: string, listener: library.BasicEventListener, thisArg: Object): void; } /** - *

      Registers an event listener object with an EventDispatcher object so that the listener - * receives notification of an event. You can register event listeners on all nodes in the display - * list for a specific type of event, phase, and priority.

      + * The {@link EventDispatcher} class is the base class for all classes that dispatch events. The + * {@link EventDispatcher} class implements the {@link IEventDispatcher} interface and is the base class for the + * {@link DisplayObject} class. The {@link EventDispatcher} class allows any object on the display list to be an + * event target and as such, to use the methods of the {@link IEventDispatcher} interface. * - *

      After you successfully register an event listener, you cannot change its priority through - * additional calls to addEventListener(). To change a listener's priority, you must first call - * removeListener(). Then you can register the listener again with the new priority level.

      + * The event target serves as the local point for how events flow through the display list hierarchy. When an + * event such as a mouse click or a key press occurs, an event object is dispatched into the event flow from the + * root of the display list. The event object makes a round-trip journey to the event target, which is + * conceptually divided into three phases: the capture phase includes the journey from the root to the last node + * before the event target's node; the target phase includes only the event target node; and the bubbling phase + * includes any subsequent nodes encountered on the return trip to the root of the display list. * - * Keep in mind that after the listener is registered, subsequent calls to addEventListener() - * with a different type or useCapture value result in the creation of a separate listener registration. - * For example, if you first register a listener with useCapture set to true, it listens only during the - * capture phase. If you call addEventListener() again using the same listener object, but with - * useCapture set to false, you have two separate listeners: one that listens during the capture - * phase and another that listens during the target and bubbling phases. - * - *

      You cannot register an event listener for only the target phase or the bubbling phase. Those - * phases are coupled during registration because bubbling applies only to the ancestors of the - * target node.

      - * - *

      If you no longer need an event listener, remove it by calling removeEventListener(), - * or memory problems could result. Event listeners are not automatically removed from memory - * because the garbage collector does not remove the listener as long as the dispatching object - * exists (unless the useWeakReference parameter is set to true).

      - * - *

      Copying an EventDispatcher instance does not copy the event listeners attached to it. (If your - * newly created node needs an event listener, you must attach the listener after creating the - * node.) However, if you move an EventDispatcher instance, the event listeners attached to it move - * along with it.

      - * - *

      If the event listener is being registered on a node while an event is being processed on - * this node, the event listener is not triggered during the current phase but can be triggered - * during a later phase in the event flow, such as the bubbling phase.

      - * - *

      If an event listener is removed from a node while an event is being processed on the node, it is - * still triggered by the current actions. After it is removed, the event listener is never invoked - * again (unless registered again for future processing).

      - * - *
        - *
      • Made by AS3 - http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/EventDispatcher.html - *
      + * In general, the easiest way for a user-defined class to gain event dispatching capabilities is to extend + * {@link EventDispatcher}. If this is impossible (that is, if the class is already extending another class), you + * can instead implement the {@link IEventDispatcher} interface, create an {@link EventDispatcher} member, and + * write simple hooks to route calls into the aggregated {@link EventDispatcher}. * + * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/events/EventDispatcher.html * @author Migrated by Jeongho Nam */ class EventDispatcher implements IEventDispatcher { /** - * The origin object who issuing events. + * @hidden */ - protected event_dispatcher_: IEventDispatcher; + private event_dispatcher_; /** - * Container of listeners. + * @hidden */ - protected event_listeners_: std.HashMap>>; + private event_listeners_; /** * Default Constructor. */ @@ -2168,19 +2172,19 @@ declare namespace samchon.library { } declare namespace samchon.library { /** - *

      The {@link FileReference} class provides a means to load and save files in browser level.

      + * The {@link FileReference} class provides a means to load and save files in browser level. * - *

      The {@link FileReference} class provides a means to {@link load} and {@link save} files in browser level. A + * The {@link FileReference} class provides a means to {@link load} and {@link save} files in browser level. A * browser-system dialog box prompts the user to select a file to {@link load} or a location for {@link svae}. Each * {@link FileReference} object refers to a single file on the user's disk and has properties that contain * information about the file's size, type, name, creation date, modification date, and creator type (Macintosh only). - *

      * - *

      FileReference instances are created in the following ways:

      + * + * FileReference instances are created in the following ways: *
        *
      • * When you use the new operator with the {@link FileReference} constructor: - * var myFileReference = new FileReference(); + * let myFileReference: FileReference = new FileReference(); *
        • *
      • * When you call the {@link FileReferenceList.browse} method, which creates an array of {@link FileReference} @@ -2188,23 +2192,23 @@ declare namespace samchon.library { *
        • *
      * - *

      During a load operation, all the properties of a {@link FileReference} object are populated by calls to the + * During a load operation, all the properties of a {@link FileReference} object are populated by calls to the * {@link FileReference.browse} or {@link FileReferenceList.browse} methods. During a save operation, the name * property is populated when the select event is dispatched; all other properties are populated when the complete - * event is dispatched.

      + * event is dispatched. * - *

      The {@link browse browse()} method opens an browser-system dialog box that prompts the user to select a file + * The {@link browse browse()} method opens an browser-system dialog box that prompts the user to select a file * for {@link load}. The {@link FileReference.browse} method lets the user select a single file; the * {@link FileReferenceList.browse} method lets the user select multiple files. After a successful call to the * {@link browse browse()} method, call the {@link FileReference.load} method to load one file at a time. The * {@link FileReference.save} method prompts the user for a location to save the file and initiates downloading from - * a binary or string data.

      + * a binary or string data. * - *

      The {@link FileReference} and {@link FileReferenceList} classes do not let you set the default file location + * The {@link FileReference} and {@link FileReferenceList} classes do not let you set the default file location * for the dialog box that the {@link browse} or {@link save} methods generate. The default location shown in the * dialog box is the most recently browsed folder, if that location can be determined, or the desktop. The classes do * not allow you to read from or write to the transferred file. They do not allow the browser that initiated the - * {@link load} or {@link save} to access the loaded or saved file or the file's location on the user's disk.

      + * {@link load} or {@link save} to access the loaded or saved file or the file's location on the user's disk. * * @references http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/FileReference.html * @author Jeongho Nam @@ -2223,148 +2227,144 @@ declare namespace samchon.library { */ constructor(); /** - *

      The data from the loaded file after a successful call to the {@link load load()} method.

      + * The data from the loaded file after a successful call to the {@link load load()} method. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ data: any; /** - *

      The name of the file on the local disk.

      + * The name of the file on the local disk. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ name: string; /** - *

      The filename extension.

      + * The filename extension. * - *

      A file's extension is the part of the name following (and not including) the final dot ("."). If - * there is no dot in the filename, the extension is null.

      + * A file's extension is the part of the name following (and not including) the final dot ("."). If + * there is no dot in the filename, the extension is null. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ extension: string; /** - *

      The file type, metadata of the {@link extension}.

      + * The file type, metadata of the {@link extension}. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ type: string; /** - *

      The size of the file on the local disk in bytes.

      + * The size of the file on the local disk in bytes. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ size: number; /** - *

      The date that the file on the local disk was last modified.

      + * The date that the file on the local disk was last modified. * - *

      If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), - * an {@link LogicError exception} will be thrown when you try to get the value of this property.

      + * If the {@link FileReference} object was not populated (by a valid call to {@link FileReference.browse}), + * an {@link LogicError exception} will be thrown when you try to get the value of this property. + * + * All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. * - *

      All the properties of a {@link FileReference} object are populated by calling the {@link browse browse()}. - *

      */ modificationDate: Date; /** - * @hidden - */ - _Set_file(val: File): void; - /** - *

      Displays a file-browsing dialog box that lets the user select a file to upload. The dialog box is native + * Displays a file-browsing dialog box that lets the user select a file to upload. The dialog box is native * to the user's browser system. The user can select a file on the local computer or from other systems, for - * example, through a UNC path on Windows.

      + * example, through a UNC path on Windows. * - *

      When you call this method and the user successfully selects a file, the properties of this + * When you call this method and the user successfully selects a file, the properties of this * {@link FileReference} object are populated with the properties of that file. Each subsequent time that the * {@link FileReference.browse} method is called, the {@link FileReference} object's properties are reset to * the file that the user selects in the dialog box. Only one {@link browse browse()} can be performed at a time - * (because only one dialog box can be invoked at a time).

      + * (because only one dialog box can be invoked at a time). * - *

      Using the typeFilter parameter, you can determine which files the dialog box displays.

      + * Using the *typeFilter parameter*, you can determine which files the dialog box displays. * * @param typeFilter An array of filter strings used to filter the files that are displayed in the dialog box. * If you omit this parameter, all files are displayed. */ browse(...typeFilter: string[]): void; /** - *

      Starts the load of a local file selected by a user.

      + * Starts the load of a local file selected by a user. * - *

      You must call the {@link FileReference.browse} or {@link FileReferenceList.browse} method before you call - * the {@link load load()} method.

      + * You must call the {@link FileReference.browse} or {@link FileReferenceList.browse} method before you call + * the {@link load load()} method. * - *

      Listeners receive events to indicate the progress, success, or failure of the load. Although you can use + * Listeners receive events to indicate the progress, success, or failure of the load. Although you can use * the {@link FileReferenceList} object to let users select multiple files to load, you must {@link load} the * {@link FileReferenceList files} one by one. To {@link load} the files one by one, iterate through the - * {@link FileReferenceList.fileList} array of {@link FileReference} objects.

      + * {@link FileReferenceList.fileList} array of {@link FileReference} objects. * - *

      If the file finishes loading successfully, its contents are stored in the {@link data} property.

      + * If the file finishes loading successfully, its contents are stored in the {@link data} property. */ load(): void; /** - *

      Save a file to local filesystem.

      + * Save a file to local filesystem. * - *

      {@link FileReference.save} implemented the save function by downloading a file from a hidden anchor tag. - * However, the plan, future's {@link FileReference} will follow such rule:

      + * {@link FileReference.save} implemented the save function by downloading a file from a hidden anchor tag. + * However, the plan, future's {@link FileReference} will follow such rule: * - *

      Opens a dialog box that lets the user save a file to the local filesystem.

      + * Opens a dialog box that lets the user save a file to the local filesystem. * - *

      The {@link save save()} method first opens an browser-system dialog box that asks the user to enter a + * The {@link save save()} method first opens an browser-system dialog box that asks the user to enter a * filename and select a location on the local computer to save the file. When the user selects a location and * confirms the save operation (for example, by clicking Save), the save process begins. Listeners receive events * to indicate the progress, success, or failure of the save operation. To ascertain the status of the dialog box * and the save operation after calling {@link save save()}, your code must listen for events such as cancel, - * open, progress, and complete.

      + * open, progress, and complete. * - *

      When the file is saved successfully, the properties of the {@link FileReference} object are populated with - * the properties of the local file. The complete event is dispatched if the save is successful.

      + * When the file is saved successfully, the properties of the {@link FileReference} object are populated with + * the properties of the local file. The complete event is dispatched if the save is successful. * - *

      Only one {@link browse browse()} or {@link save()} session can be performed at a time (because only one - * dialog box can be invoked at a time).

      + * Only one {@link browse browse()} or {@link save()} session can be performed at a time (because only one + * dialog box can be invoked at a time). * * @param data The data to be saved. The data can be in one of several formats, and will be treated appropriately. * @param fileName File name to be saved. */ save(data: string, fileName: string): void; /** - *

      Save a file to local filesystem.

      + * Save a file to local filesystem. * - *

      {@link FileReference.save} implemented the save function by downloading a file from a hidden anchor tag. - * However, the plan, future's {@link FileReference} will follow such rule:

      + * {@link FileReference.save} implemented the save function by downloading a file from a hidden anchor tag. + * However, the plan, future's {@link FileReference} will follow such rule: * - *

      Opens a dialog box that lets the user save a file to the local filesystem.

      + * Opens a dialog box that lets the user save a file to the local filesystem. * - *

      The {@link save save()} method first opens an browser-system dialog box that asks the user to enter a + * The {@link save save()} method first opens an browser-system dialog box that asks the user to enter a * filename and select a location on the local computer to save the file. When the user selects a location and * confirms the save operation (for example, by clicking Save), the save process begins. Listeners receive events * to indicate the progress, success, or failure of the save operation. To ascertain the status of the dialog box * and the save operation after calling {@link save save()}, your code must listen for events such as cancel, - * open, progress, and complete.

      + * open, progress, and complete. * - *

      When the file is saved successfully, the properties of the {@link FileReference} object are populated with - * the properties of the local file. The complete event is dispatched if the save is successful.

      + * When the file is saved successfully, the properties of the {@link FileReference} object are populated with + * the properties of the local file. The complete event is dispatched if the save is successful. * - *

      Only one {@link browse browse()} or {@link save()} session can be performed at a time (because only one - * dialog box can be invoked at a time).

      + * Only one {@link browse browse()} or {@link save()} session can be performed at a time (because only one + * dialog box can be invoked at a time). * * @param data The data to be saved. The data can be in one of several formats, and will be treated appropriately. * @param fileName File name to be saved. @@ -2372,13 +2372,13 @@ declare namespace samchon.library { static save(data: string, fileName: string): void; } /** - *

      The {@link FileReferenceList} class provides a means to let users select one or more files for + * The {@link FileReferenceList} class provides a means to let users select one or more files for * {@link FileReference.load loading}. A {@link FileReferenceList} object represents a group of one or more local * files on the user's disk as an array of {@link FileReference} objects. For detailed information and important * considerations about {@link FileReference} objects and the FileReference class, which you use with - * {@link FileReferenceList}, see the {@link FileReference} class.

      + * {@link FileReferenceList}, see the {@link FileReference} class. * - *

      To work with the {@link FileReferenceList} class:

      + * To work with the {@link FileReferenceList} class: *
        *
      • Instantiate the class: var myFileRef = new FileReferenceList();
        • *
      • @@ -2392,8 +2392,8 @@ declare namespace samchon.library { *
      • Call {@link FileReference.load} on each element in the {@link fileList} array.
        • *
      * - *

      The {@link FileReferenceList} class includes a {@link browse browse()} method and a {@link fileList} property - * for working with multiple files.

      + * The {@link FileReferenceList} class includes a {@link browse browse()} method and a {@link fileList} property + * for working with multiple files. * * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/FileReferenceList.html * @author Jeongho Nam @@ -2408,31 +2408,31 @@ declare namespace samchon.library { */ constructor(); /** - *

      An array of {@link FileReference} objects.

      + * An array of {@link FileReference} objects. * - *

      When the {@link FileReferenceList.browse} method is called and the user has selected one or more files + * When the {@link FileReferenceList.browse} method is called and the user has selected one or more files * from the dialog box that the {@link browse browse()} method opens, this property is populated with an array of - * {@link FileReference} objects, each of which represents the files the user selected.

      + * {@link FileReference} objects, each of which represents the files the user selected. * - *

      The {@link fileList} property is populated anew each time {@link browse browse()} is called on that - * {@link FileReferenceList} object.

      + * The {@link fileList} property is populated anew each time {@link browse browse()} is called on that + * {@link FileReferenceList} object. */ fileList: std.Vector; /** - *

      Displays a file-browsing dialog box that lets the user select one or more local files to upload. The - * dialog box is native to the user's browser system.

      + * Displays a file-browsing dialog box that lets the user select one or more local files to upload. The + * dialog box is native to the user's browser system. * - *

      When you call this method and the user successfully selects files, the {@link fileList} property of this + * When you call this method and the user successfully selects files, the {@link fileList} property of this * {@link FileReferenceList} object is populated with an array of {@link FileReference} objects, one for each * file that the user selects. Each subsequent time that the {@link FileReferenceList.browse} method is called, * the {@link FileReferenceList.fileList} property is reset to the file(s) that the user selects in the dialog - * box.

      + * box. * - *

      Using the typeFilter parameter, you can determine which files the dialog box displays.

      + * Using the *typeFilter* parameter, you can determine which files the dialog box displays. * - *

      Only one {@link FileReference.browse}, {@link FileReference.load}, or {@link FileReferenceList.browse} + * Only one {@link FileReference.browse}, {@link FileReference.load}, or {@link FileReferenceList.browse} * session can be performed at a time on a {@link FileReferenceList} object (because only one dialog box can be - * opened at a time).

      + * opened at a time). * * @param typeFilter An array of filter strings used to filter the files that are displayed in the dialog box. * If you omit this parameter, all files are displayed. @@ -2442,16 +2442,15 @@ declare namespace samchon.library { } declare namespace samchon.library { /** - *

      A genetic algorithm class.

      + * A genetic algorithm class. * - * @details - *

      In the field of artificial intelligence, a genetic algorithm (GA) is a search heuristic that mimics the + * In the field of artificial intelligence, a genetic algorithm (GA) is a search heuristic that mimics the * process of natural selection. This heuristic (also sometimes called a metaheuristic) is routinely used to generate - * useful solutions to optimization and search problems.

      + * useful solutions to optimization and search problems. * - *

      Genetic algorithms belong to the larger class of evolutionary algorithms (EA), which generate solutions to + * Genetic algorithms belong to the larger class of evolutionary algorithms (EA), which generate solutions to * optimization problems using techniques inspired by natural evolution, such as inheritance, {@link mutate mutation}, - * {@link selection}, and {@link crossover}.

      + * {@link selection}, and {@link crossover}. * * @reference https://en.wikipedia.org/wiki/Genetic_algorithm * @author Jeongho Nam @@ -2488,22 +2487,22 @@ declare namespace samchon.library { */ constructor(unique?: boolean, mutation_rate?: number, tournament?: number); /** - *

      Evolove GeneArray.

      + * Evolove *GeneArray*. * - *

      Convenient method accessing to {@link evolvePopulation evolvePopulation()}.

      + * Convenient method accessing to {@link evolvePopulation evolvePopulation()}. * * @param individual An initial set of genes; sequence listing. * @param population Size of population in a generation. * @param generation Size of generation in evolution. * @param compare A comparison function returns whether left gene is more optimal. * - * @return An evolved GeneArray, optimally. + * @return An evolved *GeneArray*, optimally. * * @see {@link GAPopulation.compare} */ evolveGeneArray>(individual: GeneArray, population: number, generation: number, compare?: (left: T, right: T) => boolean): GeneArray; /** - * Evolve population, a mass of GeneArraies. + * Evolve *population*, a mass of *GeneArraies*. * * @param population An initial population. * @param compare A comparison function returns whether left gene is more optimal. @@ -2514,11 +2513,11 @@ declare namespace samchon.library { */ evolvePopulation>(population: GAPopulation, compare?: (left: T, right: T) => boolean): GAPopulation; /** - *

      Select the best GeneArray in population from tournament.

      + * Select the best GeneArray in *population* from tournament. * - *

      {@link selection Selection} is the stage of a genetic algorithm in which individual genomes are chosen + * {@link selection Selection} is the stage of a genetic algorithm in which individual genomes are chosen * from a population for later breeding (using {@linlk crossover} operator). A generic {@link selection} - * procedure may be implemented as follows:

      + * procedure may be implemented as follows: * *
        *
      1. @@ -2543,14 +2542,14 @@ declare namespace samchon.library { */ private selection(population); /** - *

        Create a new GeneArray by crossing over two GeneArray(s).

        + * Create a new GeneArray by crossing over two *GeneArray*(s). * - *

        {@link crossover} is a genetic operator used to vary the programming of a chromosome or chromosomes from + * {@link crossover} is a genetic operator used to vary the programming of a chromosome or chromosomes from * one generation to the next. It is analogous to reproduction and biological crossover, upon which genetic - * algorithms are based.

        + * algorithms are based. * - *

        {@link crossover Cross over} is a process of taking more than one parent solutions and producing a child - * solution from them. There are methods for selection of the chromosomes.

        + * {@link crossover Cross over} is a process of taking more than one parent solutions and producing a child + * solution from them. There are methods for selection of the chromosomes. * * @param parent1 A parent sequence listing * @param parent2 A parent sequence listing @@ -2559,25 +2558,25 @@ declare namespace samchon.library { */ private crossover(parent1, parent2); /** - *

        Cause a mutation on the GeneArray.

        + * Cause a mutation on the *GeneArray*. * - *

        {@link mutate Mutation} is a genetic operator used to maintain genetic diversity from one generation of a - * population of genetic algorithm chromosomes to the next. It is analogous to biological mutation.

        + * {@link mutate Mutation} is a genetic operator used to maintain genetic diversity from one generation of a + * population of genetic algorithm chromosomes to the next. It is analogous to biological mutation. * - *

        {@link mutate Mutation} alters one or more gene values in a chromosome from its initial state. In + * {@link mutate Mutation} alters one or more gene values in a chromosome from its initial state. In * {@link mutate mutation}, the solution may change entirely from the previous solution. Hence GA can come to - * better solution by using {@link mutate mutation}.

        + * better solution by using {@link mutate mutation}. * - *

        {@link mutate Mutation} occurs during evolution according to a user-definable mutation probability. This - * probability should be set low. If it is set too high, the search will turn into a primitive random search.

        + * {@link mutate Mutation} occurs during evolution according to a user-definable mutation probability. This + * probability should be set low. If it is set too high, the search will turn into a primitive random search. * *

        Note

        - *

        Muttion is pursuing diversity. Mutation is useful for avoiding the following problem.

        + * Muttion is pursuing diversity. Mutation is useful for avoiding the following problem. * - *

        When initial set of genes(GeneArray) is far away from optimail, without mutation (only with selection and - * crossover), the genetic algorithm has a tend to wandering outside of the optimal.

        + * When initial set of genes(GeneArray) is far away from optimail, without mutation (only with selection and + * crossover), the genetic algorithm has a tend to wandering outside of the optimal. * - *

        Genes in the GeneArray will be swapped following percentage of the {@link mutation_rate}.

        + * Genes in the GeneArray will be swapped following percentage of the {@link mutation_rate}. * * @param individual A container of genes to mutate * @@ -2587,18 +2586,18 @@ declare namespace samchon.library { private mutate(individual); } /** - *

        A population in a generation.

        + * A population in a generation. * - *

        {@link GAPopulation} is a class representing population of candidate genes (sequence listing) having an array + * {@link GAPopulation} is a class representing population of candidate genes (sequence listing) having an array * of GeneArray as a member. {@link GAPopulation} also manages initial set of genes and handles fitting test direclty - * by the method {@link fitTest fitTest()}.

        + * by the method {@link fitTest fitTest()}. * - *

        The success of evolution of genetic algorithm is depend on the {@link GAPopulation}'s initial set and fitting - * test. (GeneArray and {@link compare}.)

        + * The success of evolution of genetic algorithm is depend on the {@link GAPopulation}'s initial set and fitting + * test. (*GeneArray* and {@link compare}.) * *

        Warning

        - *

        Be careful for the mistakes of direction or position of the {@link compare}.

        - *

        Most of logical errors failed to access optimal solution are occured from those mistakes.

        + * Be careful for the mistakes of direction or position of the {@link compare}. + * Most of logical errors failed to access optimal solution are occured from those mistakes. * * @param Type of gene elements. * @param An array containing genes as elments; sequnce listing. @@ -2611,10 +2610,10 @@ declare namespace samchon.library { */ private children_; /** - *

        A comparison function returns whether left gene is more optimal, greater.

        + * A comparison function returns whether left gene is more optimal, greater. * - *

        Default value of this {@link compare} is {@link std.greater}. It means to compare two array - * (GeneArray must be a type of {@link std.base.IArrayContainer}). Thus, you've to keep follwing rule.

        + * Default value of this {@link compare} is {@link std.greater}. It means to compare two array + * (GeneArray must be a type of {@link std.base.IArrayContainer}). Thus, you've to keep follwing rule. * *
          *
        • GeneArray is implemented from {@link std.base.IArrayContainer}.
          • @@ -2625,50 +2624,50 @@ declare namespace samchon.library { *
        • GeneArray has custom public less(obj: T): boolean; function.
          • *
        * - *

        If you don't want to follow the rule or want a custom comparison function, you have to realize a - * comparison function.

        + * If you don't want to follow the rule or want a custom comparison function, you have to realize a + * comparison function. */ private compare_; /** - *

        Private constructor with population.

        + * Private constructor with population. * - *

        Private constructor of GAPopulation does not create {@link children}. (candidate genes) but only assigns - * null repeatedly following the population size.

        + * Private constructor of GAPopulation does not create {@link children}. (candidate genes) but only assigns + * *null* repeatedly following the *population size*. * - *

        This private constructor is designed only for {@link GeneticAlgorithm}. Don't create {@link GAPopulation} - * with this constructor, by yourself.

        + * This private constructor is designed only for {@link GeneticAlgorithm}. Don't create {@link GAPopulation} + * with this constructor, by yourself. * * @param size Size of the population. */ constructor(size: number); /** - *

        Construct from a {@link GeneArray} and size of the population.

        + * Construct from a {@link GeneArray} and *size of the population*. + * + * This public constructor creates *GeneArray(s)* as population (size) having shuffled genes which are + * came from the initial set of genes (*geneArray*). It uses {@link std.greater} as default comparison function. * - *

        This public constructor creates GeneArray(s) as population (size) having shuffled genes which are - * came from the initial set of genes (geneArray). It uses {@link std.greater} as default comparison function. - *

        * * @param geneArray An initial sequence listing. * @param size The size of population to have as children. */ constructor(geneArray: GeneArray, size: number); /** - *

        Constructor from a GeneArray, size of the poluation and custom comparison function.

        + * Constructor from a GeneArray, size of the poluation and custom comparison function. + * + * This public constructor creates *GeneArray(s)* as population (size) having shuffled genes which are + * came from the initial set of genes (*geneArray*). The *compare* is used for comparison function. * - *

        This public constructor creates GeneArray(s) as population (size) having shuffled genes which are - * came from the initial set of genes (geneArray). The compare is used for comparison function. - *

        * * @param geneArray An initial sequence listing. * @param size The size of population to have as children. * @param compare A comparison function returns whether left gene is more optimal. */ constructor(geneArray: GeneArray, size: number, compare: (left: GeneArray, right: GeneArray) => boolean); - _Get_children(): std.Vector; + children(): std.Vector; /** - * Test fitness of each GeneArray in the {@link population}. + * Test fitness of each *GeneArray* in the {@link population}. * - * @return The best GeneArray in the {@link population}. + * @return The best *GeneArray* in the {@link population}. */ fitTest(): GeneArray; /** @@ -2679,32 +2678,30 @@ declare namespace samchon.library { } declare namespace samchon.library { /** - *

        A utility class supporting static methods of string.

        + * A utility class supporting static methods of string. * - *

        The {@link StringUtil} utility class is an all-static class with methods for working with string objects within - * Samchon Framework. You do not create instances of {@link StringUtil}; instead you call methods such as the - * StringUtil.substitute() method.

        + * The {@link StringUtil} utility class is an all-static class with methods for working with string objects. + * You do not create instances of {@link StringUtil}; instead you call methods such as the + * ```StringUtil.substitute()``` method. * * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/mx/utils/StringUtil.html * @author Jeongho Nam */ class StringUtil { /** - *

        Generate a substring.

        + * Generate a substring. * - *

        Extracts a substring consisting of the characters from specified start to end. - * It's same with str.substring( ? = (str.find(start) + start.size()), str.find(end, ?) )

        + * Extracts a substring consisting of the characters from specified start to end. + * It's same with str.substring( ? = (str.find(start) + start.size()), str.find(end, ?) ) * - * - let str = between("ABCD[EFGH]IJK", "[", "]"); - console.log(str); // PRINTS "EFGH" - * + * ```typescript + * let str: string = StringUtil.between("ABCD(EFGH)IJK", "(", ")"); + * console.log(str); // PRINTS "EFGH" + * ``` * - *
          - *
        • If start is not specified, extracts from begin of the string to end.
          • - *
        • If end is not specified, extracts from start to end of the string.
          • - *
        • If start and end are all omitted, returns str, itself.
          • - *
        + * - If start is not specified, extracts from begin of the string to end.
        2. + * - If end is not specified, extracts from start to end of the string. + * - If start and end are all omitted, returns str, itself. * * @param str Target string to be applied between. * @param start A string for separating substring at the front. @@ -2714,15 +2711,15 @@ declare namespace samchon.library { */ static between(str: string, start?: string, end?: string): string; /** - *

        Fetch substrings.

        + * Fetch substrings. * - *

        Splits a string into an array of substrings dividing by specified delimeters of start and end. - * It's the array of substrings adjusted the between.

        + * Splits a string into an array of substrings dividing by specified delimeters of start and end. + * It's the array of substrings adjusted the between. * *
          *
        • If startStr is omitted, it's same with the split by endStr not having last item.
          • *
        • If endStr is omitted, it's same with the split by startStr not having first item.
          • - *
        • If startStr and endStar are all omitted, returns str.
          • + *
        • If startStr and endStar are all omitted, returns *str*.
          • *
        * * @param str Target string to split by between. @@ -2770,7 +2767,7 @@ declare namespace samchon.library { * @param format The string to make substitutions in. This string can contain special tokens of the form * {n}, where n is a zero based index, that will be replaced with the * additional parameters found at that index if specified. - * @param args Additional parameters that can be substituted in the format parameter at each + * @param args Additional parameters that can be substituted in the *format* parameter at each * {n} location, where n is an integer (zero based) index value into * the array of values specified. * @@ -2803,9 +2800,9 @@ declare namespace samchon.library { */ static removeHTMLSpaces(str: string): string; /** - *

        Repeat a string.

        + * Repeat a string. * - *

        Returns a string consisting of a specified string concatenated with itself a specified number of times.

        + * Returns a string consisting of a specified string concatenated with itself a specified number of times. * * @param str The string to be repeated. * @param n The repeat count. @@ -2814,9 +2811,9 @@ declare namespace samchon.library { */ static repeat(str: string, n: number): string; /** - *

        Number to formatted string with "," sign.

        + * Number to formatted string with "," sign. * - *

        Returns a string converted from the number rounded off from specified precision with "," symbols.

        + * Returns a string converted from the number rounded off from specified precision with "," symbols. * * @param val A number wants to convert to string. * @param precision Target precision of round off. @@ -2829,14 +2826,12 @@ declare namespace samchon.library { } declare namespace samchon.library { /** - *

        URLVariables class is for representing variables of HTTP.

        + * URLVariables class is for representing variables of HTTP. * - *

        URLVariables class allows you to transfer variables between an application and server. - * When transfering, URLVariables will be converted to a URI string.

        + * {@link URLVariables} class allows you to transfer variables between an application and server. * - *
          - *
        • URI: Uniform Resource Identifier
          • - *
        + * When transfering, {@link URLVariables} will be converted to a *URI* string. + * - URI: Uniform Resource Identifier * * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/net/URLVariables.html * @author Migrated by Jeongho Nam @@ -2847,9 +2842,9 @@ declare namespace samchon.library { */ constructor(); /** - *

        Construct from a URL-encoded string.

        + * Construct from a URL-encoded string. * - *

        The {@link decode decode()} method is automatically called to convert the string to properties of the {@link URLVariables} object.

        + * The {@link decode decode()} method is automatically called to convert the string to properties of the {@link URLVariables} object. * * @param str A URL-encoded string containing name/value pairs. */ @@ -2866,48 +2861,369 @@ declare namespace samchon.library { toString(): string; } } +declare namespace samchon.library { + /** + * A tree-structured XML object. + * + * The {@link XML| class contains methods and properties for working with XML objects. The {@link XML} class (along + * with the {@link XMLList}) implements the powerful XML-handling standards defined in ECMAScript for XML (E4X) + * specification (ECMA-357 edition 2). + * + * An XML object, it is composed with three members; {@link getTag tag}, {@link getProperty properties} and + * {@link getValue value}. As you know, XML is a tree structured data expression method. The tree-stucture; + * {@link XML} class realizes it by extending ```std.HashMap```. Child {@link XML} objects are + * contained in the matched {@link XMLList} object being grouped by their {@link getTag tag name}. The + * {@link XMLList} objects, they're stored in the {@link std.HashMap} ({@link XML} itself) with its **key**; common + * {@link getTag tag name} of children {@link XML} objects. + * + * ```typescript + * class XML extends std.HashMap + * { + * private tag_: string; + * private properties_: std.HashMap; + * private value_: string; + * } + * ``` + * + * ```xml + * + * + * + * {value} + * {value} + * {value} + * + * + * + * + * ``` + * + * Use the {@link toString toString()} method to return a string representation of the {@link XML} object regardless + * of whether the {@link XML} object has simple content or complex content. + * + * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/XML.html + * @handbook https://github.com/samchon/framework/wiki/TypeScript-Library-XML + * @author Jeongho Nam + */ + class XML extends std.HashMap { + /** + * @hidden + */ + private tag_; + /** + * @hidden + */ + private value_; + /** + * @hidden + */ + private property_map_; + /** + * Default Constructor. + */ + constructor(); + /** + * Construct from string. + * + * Creates {@link XML} object by parsing a string who represents xml structure. + * + * @param str A string represents XML structure. + */ + constructor(str: string); + /** + * @hidden + */ + private parse(str); + /** + * @hidden + */ + private parse_tag(str); + /** + * @hidden + */ + private parse_properties(str); + /** + * @hidden + */ + private parse_value(str); + /** + * @hidden + */ + private parse_children(str); + /** + * Get tag. + * + * ```xml + * {value} + * ``` + * + * @return tag. + */ + getTag(): string; + /** + * Get value. + * + * ```xml + * {VALUE} + * ``` + * + * @return value. + */ + getValue(): string; + /** + * Test whether a property exists. + * + * ```xml + * {value} + * ``` + * + * @return Whether a property has the *key* exists or not. + */ + hasProperty(key: string): boolean; + /** + * Get property. + * + * Get property by its *key*, property name. If the matched *key* does not exist, then exception + * {@link std.OutOfRange} is thrown. Thus, it would better to test whether the *key* exits or not by calling the + * {@link hasProperty hasProperty()} method before calling this {@link getProperty getProperty()}. + * + * This method can be substituted by {@link getPropertyMap getPropertyMap()} such below: + * - ```getPropertyMap().get(key, value);``` + * - ```getPropertyMap().find(key).second;``` + * + * ```xml + * {value} + * ``` + * + * @return Value of the matched property. + */ + getProperty(key: string): string; + /** + * Get property map. + * + * ```xml + * {value} + * ``` + * + * @return {@link HashMap} containing properties' keys and values. + */ + getPropertyMap(): std.HashMap; + /** + * Set tag. + * + * Set tag name, identifier of this {@link XML} object. + * + * If this {@link XML} object is belonged to, a child of, an {@link XMLList} and its related {@link XML} objects, + * then calling this {@link setTag setTag()} method direclty is not recommended. Erase this {@link XML} object + * from parent objects and insert this object again. + * + * ```xml + * {value} + * ``` + * + * @param val To be new {@link getTag tag}. + */ + setTag(val: string): void; + /** + * Set value. + * + * ```xml + * {VALUE} + * ``` + * + * @param val To be new {@link getValue value}. + */ + setValue(val: string): void; + /** + * Set property. + * + * Set a property *value* with its *key*. If the *key* already exists, then the *value* will be overwritten to + * the property. Otherwise the *key* is not exist yet, then insert the *key* and *value* {@link Pair pair} to + * {@link getPropertyMao property map}. + * + * This method can be substituted by {@link getPropertyMap getPropertyMap()} such below: + * - ```getPropertyMap().set(key, value);``` + * - ```getPropertyMap().emplace(key, value);``` + * - ```getPropertyMap().insert([key, value]);``` + * - ```getPropertyMap().insert(std.make_pair(key, value));``` + * + * ```xml + * {value} + * ``` + * + * @param key Key, identifier of property to be newly inserted. + * @param value Value of new property to be newly inserted. + */ + setProperty(key: string, value: string): void; + /** + * Erase property. + * + * Erases a property by its *key*, property name. If the matched *key* does not exist, then exception + * {@link std.OutOfRange} is thrown. Thus, it would better to test whether the *key* exits or not by calling the + * {@link hasProperty hasProperty()} method before calling this {@link eraseProperty eraseProperty()}. + * + * This method can be substituted by ``getPropertyMap().erase(key)````. + * + * ```xml + * {value} + * ``` + * + * @param key Key of the property to erase + * @throw {@link std.OutOfRange} + */ + eraseProperty(key: string): void; + /** + * @hidden + */ + push(...args: std.Pair[]): number; + /** + * @hidden + */ + push(...args: [string, XMLList][]): number; + push(...xmls: XML[]): number; + push(...xmlLists: XMLList[]): number; + /** + * Add all properties from other {@link XML} object. + * + * All the properties in the *obj* are copied to this {@link XML} object. If this {@link XML} object has same + * property key in the *obj*, then value of the property will be replaced to *obj*'s own. If you don't want to + * overwrite properties with same key, then use {@link getPropertyMap getPropertyMap()} method. + * + * ```typescript + * let x: library.XML; + * let y: library.XML; + * + * x.addAllProperties(y); // duplicated key exists, then overwrites + * x.getPropertyMap().insert(y.getPropertyMap().begin(), y.getPropertyMap().end()); + * // ducpliated key, then ignores. only non-duplicateds are copied. + * ``` + * + * ```xml + * {value} + * ``` + * + * @param obj Target {@link XML} object to copy properties. + */ + addAllProperties(obj: XML): void; + /** + * Clear properties. + * + * Remove all properties. It's same with calling ```getPropertyMap().clear()```. + * + * ```xml + * {value} + * ``` + */ + clearProperties(): void; + /** + * @hidden + */ + private compute_min_index(...args); + /** + * @hidden + */ + private decode_value(str); + /** + * @hidden + */ + private encode_value(str); + /** + * @hidden + */ + private decode_property(str); + /** + * @hidden + */ + private encode_property(str); + /** + * {@link XML} object to xml string. + * + * Returns a string representation of the {@link XML} object. + * + * @param tab Number of tabs to spacing. + * @return The string representation of the {@link XML} object. + */ + toString(tab?: number): string; + } +} +declare namespace samchon.library { + /** + * List of {@link XML} objects with same tag. + * + * @reference http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/XMLList.html + * @handbook https://github.com/samchon/framework/wiki/TypeScript-Library-XML + * @author Jeongho Nam + */ + class XMLList extends std.Deque { + /** + * Get tag. + */ + getTag(): string; + /** + * {@link XMLList XML objects} to string. + * + * Returns a string representation of the {@link XMLList XML objects}. + * + * @param tab Number of tabs to spacing. + * @return The string representation of the {@link XMLList XML objects}. + */ + toString(level?: number): string; + } +} declare namespace samchon.protocol { /** - *

        An interface of entity.

        + * An interface of entity. * - *

        Entity is a class for standardization of expression method using on network I/O by XML. If + * 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.

        + * Entity is not imposed but encouraged. * - *

        As we could get advantages from standardization of message for network I/O with Invoke, + * 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.

        + * need to how network communications are being done. * - *

        I say repeatedly. Expression method of Entity is recommended, but not imposed. It's a semi + * 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.

        + * 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, + * If your own network system has a critical performance issue on communication data class, * it would be better to using binary communication (with ByteArray). - * Don't worry about the problem! Invoke also provides methods for binary data (ByteArray).

        + * Don't worry about the problem! Invoke also provides methods for binary data (ByteArray). * * @author Jeongho Nam */ interface IEntity { /** - *

        Construct data of the Entity from a XML object.

        + * Construct data of the Entity from a XML object. * - *

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

        + * 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.

        + * By recommended guidance, data representing member variables are contained in properties + * of the put XML object. * * @param xml An xml used to contruct data of entity. */ construct(xml: library.XML): void; /** - *

        Get a key that can identify the Entity uniquely.

        + * Get a key that can identify the Entity uniquely. * - *

        If identifier of the Entity is not atomic value, returns a paired or tuple object - * that can represents the composite identifier.

        + * If identifier of the Entity is not atomic value, returns a paired or tuple object + * that can represents the composite identifier. * * * class Point extends Entity @@ -2924,22 +3240,22 @@ declare namespace samchon.protocol { */ key(): any; /** - *

        A tag name when represented by XML.

        + * A tag name when represented by XML. * * */ TAG(): string; /** - *

        Get a XML object represents the Entity.

        + * Get a XML object represents the Entity. * - *

        A member variable (not object, but atomic value like number, string or date) is categorized + * 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 a XML object.

        + * belongs to only a XML object. * - *

        Don't archive the member variable of atomic value to XML::value causing enormouse creation + * 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 a XML - * instance (tag).

        + * instance (tag). * *

        Standard Usage.

        * @@ -2975,26 +3291,26 @@ declare namespace samchon.protocol { function toXML(entity: IEntity, ...prohibited_names: string[]): library.XML; } /** - *

        An entity, a standard data class.

        + * An entity, a standard data class. * - *

        Entity is a class for standardization of expression method using on network I/O by XML. If + * 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.

        + * Entity is not imposed but encouraged. * - *

        As we could get advantages from standardization of message for network I/O with Invoke, + * 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.

        + * need to how network communications are being done. * - *

        I say repeatedly. Expression method of Entity is recommended, but not imposed. It's a semi + * 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.

        + * 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, + * If your own network system has a critical performance issue on communication data class, * it would be better to using binary communication (with ByteArray). - * Don't worry about the problem! Invoke also provides methods for binary data (ByteArray).

        + * Don't worry about the problem! Invoke also provides methods for binary data (ByteArray). * * @author Jeongho Nam */ @@ -3020,130 +3336,742 @@ declare namespace samchon.protocol { } declare namespace samchon.protocol { /** - *

        An interface taking full charge of network communication.

        - * - *

        {@link ICommunicator} is an interface for communicator classes who take full charge of network communication - * with external system, without reference to whether the external system is a server or a client.

        - * - *

        Whenever a replied message comes from the external system, the message will be converted to an - * {@link Invoke} class and will be shifted to the {@link WebCommunicator.listener listener}'s - * {@link IProtocol.replyData replyData()} method.

        - * - * - interface ICommmunicator - { - private socket: SomeSocketClass; - - // LISTENER LISTENS INVOKE MESSAGE BY IT'S IProtocol.replyData() METHOD - protected listener: IProtocol; - - // YOU CAN DETECT DISCONNECTION BY ENROLLING FUNCTION POINTER TO HERE. - public onClose: Function; - - public sendData(invoke: Invoke): void - { - this.socket.write(invoke); - } - public replyData(invoke: Invoke): void - { - // WHENEVER COMMUNICATOR GETS MESSAGE, THEN SHIFT IT TO LISTENER'S replyData() METHOD. - this.listener.replyData(invoke); - } + * @inheritdoc + */ + interface IEntityCollection extends IEntityGroup, collections.ICollection { } - * +} +declare namespace samchon.protocol { + /** + * @inheritdoc + */ + abstract class EntityArrayCollection extends collections.ArrayCollection implements IEntityCollection { + /** + * @inheritdoc + */ + construct(xml: library.XML): void; + /** + * @inheritdoc + */ + abstract createChild(xml: library.XML): T; + /** + * @inheritdoc + */ + key(): any; + /** + * @inheritdoc + */ + has(key: any): boolean; + /** + * @inheritdoc + */ + count(key: any): number; + /** + * @inheritdoc + */ + get(key: any): T; + /** + * @inheritdoc + */ + abstract TAG(): string; + /** + * @inheritdoc + */ + abstract CHILD_TAG(): string; + /** + * @inheritdoc + */ + toXML(): library.XML; + } +} +declare namespace samchon.protocol { + /** + * @inheritdoc + */ + abstract class EntityListCollection extends collections.ListCollection implements IEntityCollection { + /** + * @inheritdoc + */ + construct(xml: library.XML): void; + /** + * @inheritdoc + */ + abstract createChild(xml: library.XML): T; + /** + * @inheritdoc + */ + key(): any; + /** + * @inheritdoc + */ + has(key: any): boolean; + /** + * @inheritdoc + */ + count(key: any): number; + /** + * @inheritdoc + */ + get(key: any): T; + /** + * @inheritdoc + */ + abstract TAG(): string; + /** + * @inheritdoc + */ + abstract CHILD_TAG(): string; + /** + * @inheritdoc + */ + toXML(): library.XML; + } +} +declare namespace samchon.protocol { + /** + * @inheritdoc + */ + abstract class EntityDequeCollection extends collections.DequeCollection implements IEntityCollection { + /** + * @inheritdoc + */ + construct(xml: library.XML): void; + /** + * @inheritdoc + */ + abstract createChild(xml: library.XML): T; + /** + * @inheritdoc + */ + key(): any; + /** + * @inheritdoc + */ + has(key: any): boolean; + /** + * @inheritdoc + */ + count(key: any): number; + /** + * @inheritdoc + */ + get(key: any): T; + /** + * @inheritdoc + */ + abstract TAG(): string; + /** + * @inheritdoc + */ + abstract CHILD_TAG(): string; + /** + * @inheritdoc + */ + toXML(): library.XML; + } +} +/** + * A template for External Systems Manager. + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ +declare namespace samchon.templates.external { + /** + * An array and manager of {@link ExternalSystem external system drivers}. * - *

        + * + * + * + * #### Proxy Pattern + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *

          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalSystemArray extends protocol.EntityDequeCollection implements protocol.IProtocol { + /** + * Default Constructor. + */ + constructor(); + /** + * @hidden + */ + private handle_system_erase(event); + /** + * Test whether the role exists. + * + * @param name Name, identifier of target {@link ExternalSystemRole role}. + * + * @return Whether the role has or not. + */ + hasRole(name: string): boolean; + /** + * Get a role. + * + * @param name Name, identifier of target {@link ExternalSystemRole role}. + * + * @return The specified role. + */ + getRole(name: string): ExternalSystemRole; + /** + * Send an {@link Invoke} message. + * + * @param invoke An {@link Invoke} message to send. + */ + sendData(invoke: protocol.Invoke): void; + /** + * Handle an {@Invoke} message have received. + * + * @param invoke An {@link Invoke} message have received. + */ + replyData(invoke: protocol.Invoke): void; + /** + * Tag name of the {@link ExternalSytemArray} in {@link XML}. + * + * @return *systemArray*. + */ + TAG(): string; + /** + * Tag name of {@link ExternalSystem children elements} belonged to the {@link ExternalSytemArray} in {@link XML}. + * + * @return *system*. + */ + CHILD_TAG(): string; + } +} +/** + * A template for Parallel Processing System. + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ +declare namespace samchon.templates.parallel { + /** + * Master of Parallel Processing System. + * + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to **slave** systems and the + * children {@link ParallelSystem} objects represent the remote **slave** systems, who is being requested the + * *parallel processes*. + * + * You can specify this {@link ParallelSystemArray} class to be *a server accepting parallel clients* or + * *a client connecting to parallel servers*. Even both of them is possible. Extends one of them below and overrides + * abstract factory method(s) creating the child {@link ParallelSystem} object. + * + * - {@link ParallelClientArray}: A server accepting {@link ParallelSystem parallel clients}. + * - {@link ParallelServerArray}: A client connecting to {@link ParallelServer parallel servers}. + * - {@link ParallelServerClientArray}: Both of them. Accepts {@link ParallelSystem parallel clients} and connects to + * {@link ParallelServer parallel servers} at the same time. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + abstract class ParallelSystemArray extends external.ExternalSystemArray { + /** + * @hidden + */ + private history_sequence_; + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + at(index: number): ParallelSystem; + /** + * Send an {@link Invoke} message with segment size. + * + * Sends an {@link Invoke} message requesting a **parallel process** with its *segment size*. The {@link Invoke} + * message will be delivered to children {@link ParallelSystem} objects with the *piece size*, which is divided + * from the *segment size*, basis on their {@link ParallelSystem.getPerformance performance indices}. + * + * - If segment size is 100, + * - The segment will be allocated such below: + * + * Name | Performance index | Number of pieces to be allocated | Formula + * --------|-------------------|----------------------------------|-------------- + * Snail | 1 | 10 | 100 / 10 * 1 + * Cheetah | 4 | 40 | 100 / 10 * 4 + * Rabbit | 3 | 30 | 100 / 10 * 3 + * Turtle | 2 | 20 | 100 / 10 * 2 + * + * When the **parallel process** has completed, then this {@link ParallelSystemArraY} will estimate + * {@link ParallelSystem.getPerformance performance indices} of {@link ParallelSystem} objects basis on their + * execution time. + * + * @param invoke An {@link Invoke} message requesting parallel process. + * @param size Number of pieces to segment. + * + * @see {@link sendPieceData}, {@link ParallelSystem.getPerformacen} + */ + sendSegmentData(invoke: protocol.Invoke, size: number): void; + /** + * Send an {@link Invoke} message with range of pieces. + * + * Sends an {@link Invoke} message requesting a **parallel process** with its *range of pieces [first, last)*. + * The {@link Invoke} will be delivered to children {@link ParallelSystem} objects with the newly computed + * *range of sub-pieces*, which is divided from the *range of pieces (first to last)*, basis on their + * {@link ParallelSystem.getPerformance performance indices}. + * + * - If indices of pieces are 0 to 50, + * - The sub-pieces will be allocated such below: + * + * Name | Performance index | Range of sub-pieces to be allocated | Formula + * --------|-------------------|-------------------------------------|------------------------ + * Snail | 1 | ( 0, 5] | (50 - 0) / 10 * 1 + * Cheetah | 4 | ( 5, 25] | (50 - 0) / 10 * 4 + 5 + * Rabbit | 3 | (25, 40] | (50 - 0) / 10 * 3 + 25 + * Turtle | 2 | (40, 50] | (50 - 0) / 10 * 2 + 40 + * + * When the **parallel process** has completed, then this {@link ParallelSystemArraY} will estimate + * {@link ParallelSystem.getPerformance performance indices} of {@link ParallelSystem} objects basis on their + * execution time. + * + * @param invoke An {@link Invoke} message requesting parallel process. + * @param first Initial piece's index in a section. + * @param last Final piece's index in a section. The range used is [*first*, *last*), which contains + * all the pieces' indices between *first* and *last*, including the piece pointed by index + * *first*, but not the piece pointed by the index *last*. + * + * @see {@link sendSegmentData}, {@link ParallelSystem.getPerformacen} + */ + sendPieceData(invoke: protocol.Invoke, first: number, last: number): void; + /** + * @hidden + */ + protected _Complete_history(history: protocol.InvokeHistory): boolean; + /** + * @hidden + */ + protected _Normalize_performance(): void; + } +} +/** + * A template for Distributed Processing System. + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ +declare namespace samchon.templates.distributed { + /** + * Master of Distributed Processing System. + * + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * You can specify this {@link DistributedSystemArray} class to be *a server accepting distributed clients* or + * *a client connecting to distributed servers*. Even both of them is possible. Extends one of them below and overrides + * abstract factory method(s) creating the child {@link DistributedSystem} object. + * + * - {@link DistributedClientArray}: A server accepting {@link DistributedSystem distributed clients}. + * - {@link DistributedServerArray}: A client connecting to {@link DistributedServer distributed servers}. + * - {@link DistributedServerClientArray}: Both of them. Accepts {@link DistributedSystem distributed clients} and + * connects to {@link DistributedServer distributed servers} at the same time. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedSystemArray extends parallel.ParallelSystemArray { + /** + * @hidden + */ + private process_map_; + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + construct(xml: library.XML): void; + /** + * Factory method creating a child {@link DistributedProcess process} object. + * + * @param xml {@link XML} represents the {@link DistributedProcess child} object. + * @return A new {@link DistributedProcess} object. + */ + protected abstract createProcess(xml: library.XML): DistributedProcess; + /** + * @inheritdoc + */ + at(index: number): DistributedSystem; + /** + * Get process map. + * + * Gets an {@link HashMap} containing {@link DistributedProcess} objects with their *key*. + * + * @return An {@link HasmMap> containing pairs of string and {@link DistributedProcess} object. + */ + getProcessMap(): std.HashMap; + /** + * Test whether the process exists. + * + * @param name Name, identifier of target {@link DistributedProcess process}. + * + * @return Whether the process has or not. + */ + hasProcess(name: string): boolean; + /** + * Get a process. + * + * @param name Name, identifier of target {@link DistributedProcess process}. + * + * @return The specified process. + */ + getProcess(name: string): DistributedProcess; + /** + * Insert a process. + * + * @param process A process to be inserted. + * @return Success flag. + */ + insertProcess(process: DistributedProcess): boolean; + /** + * Erase a process. + * + * @param name Name, identifier of target {@link DistributedProcess process}. + */ + eraseProcess(name: string): boolean; + /** + * @hidden + */ + protected _Complete_history(history: protocol.InvokeHistory): boolean; + /** + * @hidden + */ + private estimate_role_performance(history); + /** + * @hidden + */ + private estimate_system_performance(history); + /** + * @hidden + */ + protected _Normalize_performance(): void; + /** + * @inheritdoc + */ + toXML(): library.XML; + } +} +declare namespace samchon.templates.distributed { + /** + * Mediator of Distributed Processing System. + * + * The {@link DistributedSystemArrayMediator} class be a master for its slave systems, and be a slave to its master + * system at the same time. This {@link DistributedSystemArrayMediator} be a master system, containing and managing + * {@link DistributedSystem} objects, which represent distributed slave systems, by extending + * {@link DistributedSystemArray} class. Also, be a slave system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a master, you can specify this {@link DistributedSystemArrayMediator} class to be a master server accepting + * slave clients or a master client to connecting slave servers. Even both of them is possible. Extends one + * of them below and overrides abstract factory method(s) creating the child {@link DistributedSystem} object. + * + * - {@link DistributedClientArrayMediator}: A server accepting {@link DistributedSystem distributed clients}. + * - {@link DistributedServerArrayMediator}: A client connecting to {@link DistributedServer distributed servers}. + * - {@link DistributedServerClientArrayMediator}: Both of them. Accepts {@link DistributedSystem distributed clients} and + * connects to {@link DistributedServer distributed servers} at the same time. + * + * As a slave, you can specify this {@link DistributedSystemArrayMediator} to be a client slave connecting to master + * server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedSystemArrayMediator extends DistributedSystemArray { + /** + * @hidden + */ + private mediator_; + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method creating a {@link MediatorSystem} object. + * + * The {@link createMediator createMediator()} is an abstract method creating the {@link MediatorSystem} object. + * + * You know what? this {@link DistributedSystemArrayMediator} class be a master for its slave systems, and be a + * slave to its master system at the same time. The {@link MediatorSystem} object makes it possible; be a slave + * system. This {@link createMediator} determines specific type of the {@link MediatorSystem}. + * + * Overrides the {@link createMediator createMediator()} method to create and return one of them following which + * protocol and which type of remote connection (server or client) will be used: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * @return A newly created {@link MediatorSystem} object. + */ + protected abstract createMediator(): parallel.MediatorSystem; + /** + * Start mediator. + * + * If the {@link getMediator mediator} is a type of server, then opens the server accepting master client. + * Otherwise, the {@link getMediator mediator} is a type of client, then connects the master server. + */ + protected startMediator(): void; + /** + * Get {@link MediatorSystem} object. + * + * When you need to send an {@link Invoke} message to the master system of this + * {@link DistributedSystemArrayMediator}, then send to the {@link MediatorSystem} through this + * {@link getMediator}. + * + * ```typescript + * this.getMediator().sendData(...); + * ``` + * + * @return The {@link MediatorSystem} object. + */ + getMediator(): parallel.MediatorSystem; + /** + * @hidden + */ + protected _Complete_history(history: parallel.PRInvokeHistory): boolean; + } +} +declare namespace samchon.protocol { + /** + * An interface taking full charge of network communication. + * + * {@link ICommunicator} is an interface for communicator classes who take full charge of network communication with + * remote system, without reference to whether the remote system is a server or a client. Type of the + * {@link ICommunicator} is specified to {@link IServerConnector} and {@link IClientDriver} whether the remote system + * is a server (that I've to connect) or a client (a client connected to my server). + * + * Whenever a replied message comes from the remote system, the message will be converted to an {@link Invoke} class + * and the {@link Invoke} object will be shifted to the {@link IProtocol listener}'s + * {@link IProtocol.replyData IProtocol.replyData()} method. + * + * * - *

        + * * - * - *

        Basic Components

        - *

        What Basic Components are

        - *

        Basic Components are the smallest unit of network communication in this Samchon Framework. With - * Basic Components, you can construct any type of network system, even how the network system is enormously - * scaled and complicated, by just combinating the Basic Components.

        - * - *

        All the system templates in this framework are also being implemented by utilization of the - * Basic Compoonents.

        - * - *
          - *
        • {@link service Service} - *
        • {@link external External System} - *
        • {@link parallel Parallel System} - *
        • {@link distributed Distributed System} - *
        - * - *

        Note that, whatever the network system what you've to construct is, just concentrate on role of each system - * and attach matched Basic Components to the role, within framework of the Object-Oriented Design. - * Then construction of the network system will be much easier.

        - * - *
          - *
        • A system is a server, then use {@link IServer} or {@link IServerBase}.
          • - *
        • A server wants to handle a client has connected, then use {@link IClientDriver}.
          • - *
        • A system is a client connecting to an external server, then use {@link IServerConnector}.
          • - *
          • - *
        - * - *

        Example - System Templates

        - *

        Learning and understanding Basic Components of Samchon Framework, reading source codes and design of - * System Templates' modules will be very helpful.

        - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
        Name Source API Documents
        Cloud Service protocol/service {@link protocol.service}
        External System protocol/external {@link protocol.external}
        Parallel System protocol/parallel {@link protocol.parallel}
        Distributed System protocol/distributed {@link protocol.distributed}
        Slave System protocol/slave {@link protocol.slave}
        - * - *

        Example - Projects

        - * - * - * @see {@link IClientDriver}, {@link IServerConnector} - * @handbook Basic Components - ICommunicator + * @see {@link IClientDriver}, {@link IServerConnector}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#icommunicator) * @author Jeongho Nam */ interface ICommunicator extends IProtocol { @@ -3155,12 +4083,67 @@ declare namespace samchon.protocol { * Close connection. */ close(): void; + /** + * Test connection. + * + * Test whether this {@link ICommunicator communicator} object is connected with the remote system. If the + * connection is alive, then returns ```true```. Otherwise, the connection is not alive or this + * {@link ICommunicator communicator has not connected with the remote system yet, then returns ```false```. + * + * @return true if connected, otherwise false. + */ isConnected(): boolean; + /** + * Send message. + * + * Send {@link Invoke} message to remote system. + * + * @param invoke An {@link Invoke} message to send. + */ sendData(invoke: protocol.Invoke): void; + /** + * Handle replied message. + * + * Handles replied {@link Invoke} message recived from remove system. The {@link Invoke} message will be shifted + * to the {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} by this method. + * + * @param invoke An {@link Invoke} message received from remote system. + */ replyData(invoke: protocol.Invoke): void; } } declare namespace samchon.protocol { + /** + * An abstract, basic class for communicators. + * + * {@link CommunicatorBase} is an abstract class implemented from the {@link ICommunicator}. Mechanism of converting + * raw data to {@link Invoke} messag has realized in this abstract class. Type of this {@link CommunicatorBase} class + * is specified to as below following which protocol is used. + * + * - {@link Communicator}: Samchon Framework's own protocool. + * - {@link WebCommunicator}: Web-socket protocol + * - {@link SharedWorkerCommunicator}: SharedWorker's message protocol. + * + * #### [Inherited] {@link ICommunicator} + * {@link ICommunicator} is an interface for communicator classes who take full charge of network communication with + * remote system, without reference to whether the remote system is a server or a client. Type of the + * {@link ICommunicator} is specified to {@link IServerConnector} and {@link IClientDriver} whether the remote system + * is a server (that I've to connect) or a client (a client connected to my server). + * + * Whenever a replied message comes from the remote system, the message will be converted to an {@link Invoke} class + * and the {@link Invoke} object will be shifted to the {@link IProtocol listener}'s + * {@link IProtocol.replyData IProtocol.replyData()} method. + * + * + * + * + * + * @see {@link IClientDriver}, {@link IServerConnector}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#icommunicator) + * @author Jeongho Nam + */ abstract class CommunicatorBase implements ICommunicator { /** * @hidden @@ -3170,6 +4153,9 @@ declare namespace samchon.protocol { * @inheritdoc */ onClose: Function; + /** + * @hidden + */ protected connected_: boolean; /** * @hidden @@ -3188,7 +4174,7 @@ declare namespace samchon.protocol { */ constructor(); /** - * Construct from listener. + * Construct from *listener*. * * @param listener An {@link IProtocol} object to listen {@link Invoke} messages. */ @@ -3201,14 +4187,60 @@ declare namespace samchon.protocol { * @inheritdoc */ isConnected(): boolean; + /** + * @hidden + */ protected is_binary_invoke(): boolean; + /** + * @inheritdoc + */ abstract sendData(invoke: Invoke): void; + /** + * @inheritdoc + */ replyData(invoke: Invoke): void; + /** + * @hidden + */ protected handle_string(str: string): void; + /** + * @hidden + */ protected handle_binary(binary: Uint8Array): void; } } declare namespace samchon.protocol { + /** + * A communicator following Samchon Framework's own protocol. + * + * {@link Communicator} is an abstract class following Samchon Framework's own protocol. This {@link Communicator} + * class is specified to {@link ServerConnector} and {@link ClientDriver} whether the remote system is a server (that + * my system is connecting to) or a client (a client conneting to to my server). + * + * Note that, if one of this or remote system is web-browser based, then you don't have to use this + * {@link Communicator} class who follows Samchon Framework's own protocol. Web-browser supports only Web-socket + * protocol. Thus in that case, you have to use {@link WebCommunicator} instead. + * + * #### [Inherited] {@link ICommunicator} + * {@link ICommunicator} is an interface for communicator classes who take full charge of network communication with + * remote system, without reference to whether the remote system is a server or a client. Type of the + * {@link ICommunicator} is specified to {@link IServerConnector} and {@link IClientDriver} whether the remote system + * is a server (that I've to connect) or a client (a client connected to my server). + * + * Whenever a replied message comes from the remote system, the message will be converted to an {@link Invoke} class + * and the {@link Invoke} object will be shifted to the {@link IProtocol listener}'s + * {@link IProtocol.replyData IProtocol.replyData()} method. + * + * + * + * + * + * @see {@link ClientDriver}, {@link ServerConnector}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#icommunicator) + * @author Jeongho Nam + */ abstract class Communicator extends CommunicatorBase { /** * @hidden @@ -3266,31 +4298,42 @@ declare namespace samchon.protocol { } declare namespace samchon.protocol { /** - *

        Base class for web-communicator, {@link WebClientDriver} and {@link WebServerConnector}.

        + * A communicator following Web-socket protocol. * - *

        This class {@link WebCommunicatorBase} subrogates network communication for web-communicator classes, - * {@link WebClinetDriver} and {@link WebServerConnector}. The web-communicator and this class - * {@link WebCommunicatorBase} share same interface {@link IProtocol} and have a chain of responsibily - * relationship.

        + * {@link WebCommunicator} is an abstract class following Web-socket protocol. This {@link WebCommunicator} class is + * specified to {@link WebServerConnector} and {@link WebClientDriver} whether the remote system is a server (that my + * system is connecting to) or a client (a client conneting to to my server). * - *

        When an {@link Invoke} message was delivered from the connected remote system, then this class calls - * web-communicator's {@link WebServerConnector.replyData replyData()} method. Also, when called web-communicator's - * {@link WebClientDriver.sendData sendData()}, then {@link sendData sendData()} of this class will be caleed.

        + * Note that, one of this or remote system is web-browser based, then there's not any alternative choice. Web browser + * supports only Web-socket protocol. In that case, you've use this {@link WebCommunicator} class. * - *
          - *
        • this.replyData() -> communicator.replyData()
          • - *
        • communicator.sendData() -> this.sendData()
          • - *
        + * #### [Inherited] {@link ICommunicator} + * {@link ICommunicator} is an interface for communicator classes who take full charge of network communication with + * remote system, without reference to whether the remote system is a server or a client. Type of the + * {@link ICommunicator} is specified to {@link IServerConnector} and {@link IClientDriver} whether the remote system + * is a server (that I've to connect) or a client (a client connected to my server). * + * Whenever a replied message comes from the remote system, the message will be converted to an {@link Invoke} class + * and the {@link Invoke} object will be shifted to the {@link IProtocol listener}'s + * {@link IProtocol.replyData IProtocol.replyData()} method. + * + * + * + * + * + * @see {@link WebClientDriver}, {@link WebServerConnector}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#icommunicator) * @author Jeongho Nam */ abstract class WebCommunicator extends CommunicatorBase { /** - * Connection driver, a socket for web-socket. + * @hidden */ protected connection_: websocket.connection; /** - * Close the connection. + * @inheritdoc */ close(): void; /** @@ -3298,238 +4341,171 @@ declare namespace samchon.protocol { */ sendData(invoke: Invoke): void; /** - *

        Handle raw-data received from the remote system.

        - * - *

        Queries raw-data received from the remote system. When the raw-data represents an formal {@link Invoke} - * message, then it will be sent to the {@link replyData}.

        - * - * @param message A raw-data received from the remote system. + * @hidden */ protected handle_message(message: websocket.IMessage): void; + /** + * @hidden + */ protected handle_close(): void; } } declare namespace samchon.protocol { + /** + * A communicator for shared worker. + * + * {@link SharedWorkerCommunicator} is an abstract class for communication between SharedWorker and Web-browser. This + * {@link SharedWorkerCommunicator} is specified to {@link SharedWorkerServerConnector} and + * {@link SharedWorkerClientDriver} whether the remote system is a server (that my system is connecting to) or a client + * (a client conneting to to my server). + * + * Note that, SharedWorker is a conception only existed in web-browser. This {@link SharedWorkerCommunicator} is not + * supported in NodeJS. Only web-browser environment can utilize this {@link SharedWorkerCommunicator}. + * + * #### Why SharedWorker be a server? + * SharedWorker, it allows only an instance (process) to be created whether the SharedWorker is declared in a browser + * or multiple browsers. To integrate them, messages are being sent and received. Doesn't it seem like a relationship + * between a server and clients? Thus, Samchon Framework consider the SharedWorker as a server and browsers as + * clients. + * + * The class {@link SharedWorkerCommunicator} is designed make such relationship. From now on, SharedWorker is a + * {@link SharedWorkerServer server} and {@link SharedWorkerServerConnector browsers} are clients. Integrate the + * server and clients with this {@link SharedWorkerCommunicator}. + * + * #### [Inherited] {@link ICommunicator} + * {@link ICommunicator} is an interface for communicator classes who take full charge of network communication with + * remote system, without reference to whether the remote system is a server or a client. Type of the + * {@link ICommunicator} is specified to {@link IServerConnector} and {@link IClientDriver} whether the remote system + * is a server (that I've to connect) or a client (a client connected to my server). + * + * Whenever a replied message comes from the remote system, the message will be converted to an {@link Invoke} class + * and the {@link Invoke} object will be shifted to the {@link IProtocol listener}'s + * {@link IProtocol.replyData IProtocol.replyData()} method. + * + * + * + * + * + * @see {@link SharedWorkerClientDriver}, {@link SharedWorkerServerConnector}, {@link IProtocol} + * @reference https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#icommunicator) + * @author Jeongho Nam + */ abstract class SharedWorkerCommunicator extends CommunicatorBase { + /** + * @hidden + */ protected port_: MessagePort; + /** + * @inheritdoc + */ close(): void; /** * @inheritdoc */ sendData(invoke: Invoke): void; + /** + * @hidden + */ protected handle_message(event: MessageEvent): void; } } declare namespace samchon.protocol { /** - *

        An interface for communicator with connected client.

        + * An interface for communicator with remote client. * - *

        {@link IClientDriver} is a type of {@link ICommunicator}, specified for communication with connected client - * in a server. It takes full charge of network communication with the connected client.

        + * {@link IClientDriver} is a type of {@link ICommunicator}, specified for communication with remote client who has + * connected in a {@link IServer server}. It takes full charge of network communication with the remote client. * - *

        {@link IClientDriver} is created in {@link IServer} and delivered via + * The {@link IClientDriver} object is created and delivered from {@link IServer} and * {@link IServer.addClient IServer.addClient()}. Those are derived types from this {@link IClientDriver}, being - * created by matched {@link IServer} object.

        + * created by the matched {@link IServer} object. * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
        Derived Type Created By
        {@link ClientDrvier} {@link Server}
        {@link WebClientDrvier} {@link WebServer}
        {@link SharedWorkerClientDrvier} {@link SharedWorkerServer}
        + * Protocol | Derived Type | Created By + * ------------------------|----------------------------------|---------------------------- + * Samchon Framework's own | {@link ClientDriver} | {@link Server} + * Web-socket protocol | {@link WebClientDriver} | {@link WebServer} + * SharedWorker | {@link SharedWorkerClientDriver} | {@link SharedWorkerServer} * - *

        * - *

        + * * - *

        When you've got an {@link IClientDriver} object from the {@link IServer.addClient IServer.addClient()}, then - * specify {@link CommunicatorBase.listener listener} with {@link IClient.listen IClient.listen()}. Below codes are - * an example specifying and managing the {@link CommunicatorBase.listener listener} objects.

        - * - * - /// - /// - - // IMPORTS - import std = require("typescript-stl"); - import samchon = require("samchon-framework"); - - // SHORTCUTS - import library = samchon.library; - import protocol = samchon.protocol; - - class CalculatorServer extends protocol.Server - { - private clients: std.HashSet; - - // WHEN A CLIENT HAS CONNECTED - public addClient(driver: IClientDriver): void - { - let client: CalculatorClient = new CalculatorClient(this, driver); - this.clients.insert(client); - } - } - - class CalculatorClient extends protocol.IProtocol - { - // PARENT SERVER INSTANCE - private server: CalculatorServer; - - // COMMUNICATOR, SENDS AND RECEIVES NETWORK MESSAGE WITH CONNECTED CLIENT - private driver: protocol.IClientDriver; - - ///// - // CONSTRUCTORS - ///// - public constructor(server: CalculatorServer, driver: protocol.IClientDriver) - { - this.server = server; - this.driver = driver; - - // START LISTENING AND RESPOND CLOSING EVENT - this.driver.listen(this); // INVOKE MESSAGE WILL COME TO HERE - this.driver.onClose = this.destructor.bind(this); // DISCONNECTED HANDLER - } - public destructor(): void - { - // WHEN DISCONNECTED, THEN ERASE THIS OBJECT FROM CalculatorServer.clients. - this.server["clients"].erase(this); - } - - ///// - // INVOKE MESSAGE CHAIN - ///// - public sendData(invoke: protocol.Invoke): void - { - // CALL ICommunicator.sendData(), WHO PHYSICALLY SEND NETWORK MESSAGE - this.driver.sendData(invoke); - } - public replyData(invoke: protocol.Invoke): void - { - // FIND MATCHED MEMBER FUNCTION NAMED EQUAL TO THE invoke.getListener() - invoke.apply(this); - } - } - * - * - * - *

        Basic Components

        - *

        What Basic Components are

        - *

        Basic Components are the smallest unit of network communication in this Samchon Framework. With - * Basic Components, you can construct any type of network system, even how the network system is enormously - * scaled and complicated, by just combinating the Basic Components.

        - * - *

        All the system templates in this framework are also being implemented by utilization of the - * Basic Compoonents.

        - * - *
          - *
        • {@link service Service} - *
        • {@link external External System} - *
        • {@link parallel Parallel System} - *
        • {@link distributed Distributed System} - *
        - * - *

        Note that, whatever the network system what you've to construct is, just concentrate on role of each system - * and attach matched Basic Components to the role, within framework of the Object-Oriented Design. - * Then construction of the network system will be much easier.

        - * - *
          - *
        • A system is a server, then use {@link IServer} or {@link IServerBase}.
          • - *
        • A server wants to handle a client has connected, then use {@link IClientDriver}.
          • - *
        • A system is a client connecting to an external server, then use {@link IServerConnector}.
          • - *
          • - *
        - * - *

        Example - System Templates

        - *

        Learning and understanding Basic Components of Samchon Framework, reading source codes and design of - * System Templates' modules will be very helpful.

        - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
        Name Source API Documents
        Cloud Service protocol/service {@link protocol.service}
        External System protocol/external {@link protocol.external}
        Parallel System protocol/parallel {@link protocol.parallel}
        Distributed System protocol/distributed {@link protocol.distributed}
        Slave System protocol/slave {@link protocol.slave}
        - * - *

        Example - Projects

        - * - * - * @see {@link IServer} - * @handbook Basic Components - IClientDriver + * @see {@link IServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iclientdriver) * @author Jeongho Nam */ interface IClientDriver extends ICommunicator { /** - *

        Listen message from the newly connected client.

        + * Listen message from the newly connected client. * - *

        Starts listening message from the newly connected client. Replied message from the connected client will - * be converted to {@link Invoke} classes and shifted to the listener's - * {@link IProtocol.replyData replyData()} method.

        + * Starts listening message from the newly connected client. Replied message from the connected client will be + * converted to {@link Invoke} classes and shifted to the *listener*'s {@link IProtocol.replyData replyData()} + * method. * * @param listener A listener object to listen replied message from newly connected client in - * {@link IProtocol.replyData replyData()} as an {@link Invoke} message. + * {@link IProtocol.replyData replyData()} as an {@link Invoke} object. */ listen(listener: IProtocol): void; } } declare namespace samchon.protocol { + /** + * Communicator with remote client. + * + * {@link ClientDriver} is a class taking full charge of network communication with remote client who follows Samchon + * Framework's own protocol. This {@link ClientDriver} object is always created by {@link Server} class. When you got + * this {@link ClientDriver} object from the {@link Server.addClient Server.addClient()}, then specify + * {@link IProtocol listener} with the {@link ClientDriver.listen ClientDriver.listen()} method. + * + * #### [Inherited] {@link IClientDriver} + * {@link IClientDriver} is a type of {@link ICommunicator}, specified for communication with remote client who has + * connected in a {@link IServer server}. It takes full charge of network communication with the remote client. + * + * The {@link IClientDriver} object is created and delivered from {@link IServer} and + * {@link IServer.addClient IServer.addClient()}. Those are derived types from this {@link IClientDriver}, being + * created by the matched {@link IServer} object. + * + * Protocol | Derived Type | Created By + * ------------------------|----------------------------------|---------------------------- + * Samchon Framework's own | {@link ClientDriver} | {@link Server} + * Web-socket protocol | {@link WebClientDriver} | {@link WebServer} + * SharedWorker | {@link SharedWorkerClientDriver} | {@link SharedWorkerServer} + * + * When you've got an {@link IClientDriver} object from the {@link IServer.addClient IServer.addClient()}, then + * specify {@link IProtocol listener} with {@link IClient.listen IClient.listen()}. Whenever a replied message comes + * from the remote system, the message will be converted to an {@link Invoke} class and the {@link Invoke} object + * will be shifted to the {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * Below code is an example specifying and managing the {@link IProtocol listener} objects. + * + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * + * + * + * + * + * @see {@link Server}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iclientdriver) + * @author Jeongho Nam + */ class ClientDriver extends Communicator implements IClientDriver { + /** + * Construct from a socket. + */ constructor(socket: socket.socket); /** * @inheritdoc @@ -3538,15 +4514,65 @@ declare namespace samchon.protocol { } } declare namespace samchon.protocol { + /** + * Communicator with remote web-client. + * + * {@link WebClientDriver} is a class taking full charge of network communication with remote client who follows + * Web-socket protocol. This {@link WebClientDriver} object is always created by {@link WebServer} class. When you + * got this {@link WebClientDriver} object from the {@link WebServer.addClient WebServer.addClient()}, then specify + * {@link IProtocol listener} with the {@link WebClientDriver.listen WebClientDriver.listen()} method. + * + * Unlike other protocol, Web-socket protocol's clients notify two parameters on their connection; + * {@link getSessionID session-id} and {@link getPath path}. The {@link getSessionID session-id} can be used to + * identify *user* of each client, and the {@link getPath path} can be used which type of *service* that client wants. + * In {@link service} module, you can see the best utilization case of them. + * - {@link service.User}: utlization of the {@link getSessionID session-id}. + * - {@link service.Service}: utilization of the {@link getPath path}. + * + * #### [Inherited] {@link IClientDriver} + * {@link IClientDriver} is a type of {@link ICommunicator}, specified for communication with remote client who has + * connected in a {@link IServer server}. It takes full charge of network communication with the remote client. + * + * The {@link IClientDriver} object is created and delivered from {@link IServer} and + * {@link IServer.addClient IServer.addClient()}. Those are derived types from this {@link IClientDriver}, being + * created by the matched {@link IServer} object. + * + * Protocol | Derived Type | Created By + * ------------------------|----------------------------------|---------------------------- + * Samchon Framework's own | {@link ClientDriver} | {@link Server} + * Web-socket protocol | {@link WebClientDriver} | {@link WebServer} + * SharedWorker | {@link SharedWorkerClientDriver} | {@link SharedWorkerServer} + * + * When you've got an {@link IClientDriver} object from the {@link IServer.addClient IServer.addClient()}, then + * specify {@link IProtocol listener} with {@link IClient.listen IClient.listen()}. Whenever a replied message comes + * from the remote system, the message will be converted to an {@link Invoke} class and the {@link Invoke} object + * will be shifted to the {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * Below code is an example specifying and managing the {@link IProtocol listener} objects. + * + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * + * + * + * + * + * @see {@link WebServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iclientdriver) + * @author Jeongho Nam + */ class WebClientDriver extends WebCommunicator implements IClientDriver { /** - * Requested path. + * @hidden */ private path_; /** - * Session ID, an identifier of the remote client. + * @hidden */ private session_id_; + /** + * @hidden + */ private listening_; /** * Initialization Constructor. @@ -3571,8 +4597,62 @@ declare namespace samchon.protocol { } } declare namespace samchon.protocol { + /** + * Communicator with remote web-browser. + * + * {@link SharedWorkerClientDriver} is a class taking full charge of network communication with web browsers. This + * {@link SharedWorkerClientDriver} object is always created by {@link SharedWorkerServer} class. When you got this + * {@link SharedWorkerClientDriver} object from {@link SharedWorkerServer.addClient SharedWorkerServer.addClient()}, + * then specify {@link IProtocol listener} with the + * {@link SharedWorkerClientDriver.listen SharedWorkerClientDriver.listen()} method. + * + * #### Why SharedWorker be a server? + * SharedWorker, it allows only an instance (process) to be created whether the SharedWorker is declared in a browser + * or multiple browsers. To integrate them, messages are being sent and received. Doesn't it seem like a relationship + * between a server and clients? Thus, Samchon Framework consider the SharedWorker as a server and browsers as + * clients. + * + * The class {@link SharedWorkerCommunicator} is designed make such relationship. From now on, SharedWorker is a + * {@link SharedWorkerServer server} and {@link SharedWorkerServerConnector browsers} are clients. Integrate the + * server and clients with this {@link SharedWorkerCommunicator}. + * + * #### [Inherited] {@link IClientDriver} + * {@link IClientDriver} is a type of {@link ICommunicator}, specified for communication with remote client who has + * connected in a {@link IServer server}. It takes full charge of network communication with the remote client. + * + * The {@link IClientDriver} object is created and delivered from {@link IServer} and + * {@link IServer.addClient IServer.addClient()}. Those are derived types from this {@link IClientDriver}, being + * created by the matched {@link IServer} object. + * + * Protocol | Derived Type | Created By + * ------------------------|----------------------------------|---------------------------- + * Samchon Framework's own | {@link ClientDriver} | {@link Server} + * Web-socket protocol | {@link WebClientDriver} | {@link WebServer} + * SharedWorker | {@link SharedWorkerClientDriver} | {@link SharedWorkerServer} + * + * When you've got an {@link IClientDriver} object from the {@link IServer.addClient IServer.addClient()}, then + * specify {@link IProtocol listener} with {@link IClient.listen IClient.listen()}. Whenever a replied message comes + * from the remote system, the message will be converted to an {@link Invoke} class and the {@link Invoke} object + * will be shifted to the {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * Below code is an example specifying and managing the {@link IProtocol listener} objects. + * + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * + * + * + * + * + * @see {@link SharedWorkerServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iclientdriver) + * @author Jeongho Nam + */ class SharedWorkerClientDriver extends SharedWorkerCommunicator implements IClientDriver { - private listening; + private listening_; + /** + * Construct from a MessagePort object. + */ constructor(port: MessagePort); /** * @inheritdoc @@ -3624,47 +4704,47 @@ declare namespace samchon.protocol { */ interface IEntityGroup extends IEntity, std.base.IContainer { /** - *

        Construct data of the Entity from an XML object.

        + * Construct data of the Entity from an XML object. * - *

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

        + * Constructs the EntityArray's own member variables only from the input XML object. * - *

        Do not consider about constructing children Entity objects' data in EntityArray::construct(). + * Do not consider about constructing children Entity objects' data in EntityArray::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 EntityArray::toXML().

        + * of XML objects representing children are done by abstract method of EntityArray::toXML(). * - *

        Constructs only data of EntityArray's own.

        + * Constructs only data of EntityArray's own. */ construct(xml: library.XML): void; /** - *

        Factory method of a child Entity.

        + * Factory method of a child Entity. * - *

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

        + * methods Entity::construct() will be called by abstract method of the EntityArray::construct(). * * @return A new child Entity belongs to EntityArray. */ createChild(xml: library.XML): T; /** - *

        Get iterator to element.

        + * Get iterator to element. * - *

        Searches the container for an element with a identifier equivalent to key and returns an - * iterator to it if found, otherwise it returns an iterator to {@link end end()}.

        + * Searches the container for an element with a identifier equivalent to *key* and returns an + * iterator to it if found, otherwise it returns an iterator to {@link end end()}. * - *

        Two keys are considered equivalent if the container's comparison object returns false reflexively - * (i.e., no matter the order in which the elements are passed as arguments).

        + * Two keys are considered equivalent if the container's comparison object returns false reflexively + * (i.e., no matter the order in which the elements are passed as arguments). * - *

        Another member functions, {@link has has()} and {@link count count()}, can be used to just check - * whether a particular key exists.

        + * Another member functions, {@link has has()} and {@link count count()}, can be used to just check + * whether a particular *key* exists. * * @param key Key to be searched for - * @return An iterator to the element, if an element with specified key is found, or + * @return An iterator to the element, if an element with specified *key* is found, or * {@link end end()} otherwise. */ /** - *

        Whether have the item or not.

        + * Whether have the item or not. * - *

        Indicates whether a map has an item having the specified identifier.

        + * Indicates whether a map has an item having the specified identifier. * * @param key Key value of the element whose mapped value is accessed. * @@ -3672,19 +4752,19 @@ declare namespace samchon.protocol { */ has(key: any): boolean; /** - *

        Count elements with a specific key.

        + * Count elements with a specific key. * - *

        Searches the container for elements whose key is key and returns the number of elements found.

        + * Searches the container for elements whose key is *key* and returns the number of elements found. * * @param key Key value to be searched for. * - * @return The number of elements in the container with a key. + * @return The number of elements in the container with a *key*. */ count(key: any): number; /** - *

        Get an element

        + * Get an element * - *

        Returns a reference to the mapped value of the element identified with key.

        + * Returns a reference to the mapped value of the element identified with *key*. * * @param key Key value of the element whose mapped value is accessed. * @@ -3694,20 +4774,20 @@ declare namespace samchon.protocol { */ get(key: any): T; /** - *

        A tag name of children objects.

        + * A tag name of children objects. */ CHILD_TAG(): string; /** - *

        Get an XML object represents the EntityArray.

        + * Get an XML object represents the EntityArray. * - *

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

        + * Archives the EntityArray's own member variables only to the returned XML object. * - *

        Do not consider about archiving children Entity objects' data in EntityArray::toXML(). + * Do not consider about archiving children Entity objects' data in EntityArray::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 - * EntityArray::toXML().

        + * EntityArray::toXML(). * - *

        Archives only data of EntityArray's own.

        + * Archives only data of EntityArray's own. */ toXML(): library.XML; } @@ -3859,387 +4939,39 @@ declare namespace samchon.protocol { } declare namespace samchon.protocol { /** - * @inheritdoc - */ - interface IEntityCollection extends IEntityGroup, collection.ICollection { - } -} -declare namespace samchon.protocol { - /** - * @inheritdoc - */ - abstract class EntityArrayCollection extends collection.ArrayCollection implements IEntityCollection { - /** - * @inheritdoc - */ - construct(xml: library.XML): void; - /** - * @inheritdoc - */ - abstract createChild(xml: library.XML): T; - /** - * @inheritdoc - */ - key(): any; - /** - * @inheritdoc - */ - has(key: any): boolean; - /** - * @inheritdoc - */ - count(key: any): number; - /** - * @inheritdoc - */ - get(key: any): T; - /** - * @inheritdoc - */ - abstract TAG(): string; - /** - * @inheritdoc - */ - abstract CHILD_TAG(): string; - /** - * @inheritdoc - */ - toXML(): library.XML; - } -} -declare namespace samchon.protocol { - /** - * @inheritdoc - */ - abstract class EntityListCollection extends collection.ListCollection implements IEntityCollection { - /** - * @inheritdoc - */ - construct(xml: library.XML): void; - /** - * @inheritdoc - */ - abstract createChild(xml: library.XML): T; - /** - * @inheritdoc - */ - key(): any; - /** - * @inheritdoc - */ - has(key: any): boolean; - /** - * @inheritdoc - */ - count(key: any): number; - /** - * @inheritdoc - */ - get(key: any): T; - /** - * @inheritdoc - */ - abstract TAG(): string; - /** - * @inheritdoc - */ - abstract CHILD_TAG(): string; - /** - * @inheritdoc - */ - toXML(): library.XML; - } -} -declare namespace samchon.protocol { - /** - * @inheritdoc - */ - abstract class EntityDequeCollection extends collection.DequeCollection implements IEntityCollection { - /** - * @inheritdoc - */ - construct(xml: library.XML): void; - /** - * @inheritdoc - */ - abstract createChild(xml: library.XML): T; - /** - * @inheritdoc - */ - key(): any; - /** - * @inheritdoc - */ - has(key: any): boolean; - /** - * @inheritdoc - */ - count(key: any): number; - /** - * @inheritdoc - */ - get(key: any): T; - /** - * @inheritdoc - */ - abstract TAG(): string; - /** - * @inheritdoc - */ - abstract CHILD_TAG(): string; - /** - * @inheritdoc - */ - toXML(): library.XML; - } -} -declare namespace samchon.protocol { - /** - *

        An interface for {@link Invoke} message chain.

        + * An interface for {@link Invoke} message chain. * - *

        {@link IProtocol} is an interface for {@link Invoke} message, which is standard message of network I/O in - * Samchon Framework, chain. The {@link IProtocol} interface is used to network drivers and some classes - * which are in a relationship of Chain of Responsibility Pattern with those network drivers.

        + * {@link IProtocol} is an interface for {@link Invoke} message, which is standard message of network I/O in + * *Samchon Framework*, chain. The {@link IProtocol} interface is used to network drivers and some classes which are + * in a relationship of *Chain of Responsibility Pattern* with those network drivers. * - *

        Implements {@link IProtocol} if the class sends and handles {@link Invoke} message. Looking around source - * codes of Samchon Framework, especially System Templates, you can find out that all the classes and - * modules handling {@link Invoke} messages are always implementing this {@link IProtocol} . Yes, {@link IProtocol}, - * this is the main role you've to follow in this Samchon Framework.

        + * Implements {@link IProtocol} if the class sends and handles {@link Invoke} messages. Looking around source codes of + * the *Samchon Framework*, especially *Templates*, you can find out that all the classes and modules handling + * {@link Invoke} messages are always implementing this {@link IProtocol}. * - *

        * - *

        - * - * - *

        Utilization Case

        - *

        Below pseudo code and class diagram represents {@link service Service Module}, who can build a cloud server. - * All the classes in the pseudo code are implementing the {@link IProtocol} because all of them are handling - * {@link Invoke} message.

        - * - *
          - *
        • Server: Represents a server literally
          • - *
        • User: Represents an user being identified by its session id. User contains multiple Client objects.
          • - *
            - *
          • In browser, an user can open multiple windows. - *
              - *
            • User: A browser (like IE, Chrome and Safari). - *
            • Client: An internet browser window - *
            - *
            • - *
          - *
        • Client: Represents a browser window and it takes role of network communication with it.
          • - *
        • Service: Represents a service, domain logic.
          • - *
        - * - *

        - * - *

        - * - * - /// - /// - - // IMPORTS - import std = require("typescript-stl"); - import samchon = require("samchon-framework"); - - // SHORTCUTS - import library = samchon.library; - import collection = samchon.collection; - import protocol = samchon.protocol; - - namespace service - { - export class Server extends protocol.WebServer implements IProtocol - { - // SERVER HAS MULTIPLE USER OBJECTS - private session_map: std.HashMap; - - //------------------------ - // MESSAGE CHAIN - //------------------------ - public sendData(invoke: protocol.Invoke): void - { - // SEND INVOKE MESSAGE TO ALL USER OBJECTS - for (let it = this.session_map.begin(); !it.equal_to(this.session_map.end()); it = it.next()) - it.second.sendData(invoke); - } - public replyData(invoke: protocol.Invoke): void - { - invoke.apply(this); // HANDLE INVOKE MESSAGE BY ITSELF - } - } - - export class User extends - collection.HashMapCollection // USER HAS MULTIPLE CLIENT OBJECTS - implements IProtocol - { - private server: Server; // USER REFRES SERVER - - //------------------------ - // MESSAGE CHAIN - //------------------------ - public sendData(invoke: protocol.Invoke): void - { - // SEND INVOKE MESSAGE TO ALL CLIENT OBJECTS - for (let it = this.begin(); !it.equal_to(this.end()); it = it.next()) - it.second.sendData(invoke); - } - public replyData(invoke: protocol.Invoke): void - { - invoke.apply(this); // HANDLE INOVKE MESSAGE BY ITSELF - this.server.replyData(invoke); // OR VIA SERVER - } - } - - export class Client implements IProtocol - { - private user: User; // CLIENT REFERS USER - private service: Service; // CLIENT HAS A SERVICE OBJECT - - private driver: WebClientDriver; - - //------------------------ - // MESSAGE CHAIN - //------------------------ - public sendData(invoke: protocol.Invoke): void - { - // SEND INVOKE MESSAGE VIA driver: WebClientDriver - this.driver.sendData(invoke); - } - public replyData(invoke: protocol.Invoke): void - { - invoke.apply(this); // HANDLE INOVKE MEESAGE BY ITSELF - this.user.replyData(invoke); // OR VIA USER - - if (this.service != null) // OR VIA SERVICE - this.service.replyData(invoke); - } - } - - export class Service implements IProtocol - { - private client: Client; // SERVICE REFRES CLIENT - - //------------------------ - // MESSAGE CHAIN - //------------------------ - public sendData(invoke: protocol.Invoke): void - { - // SEND INVOKE MESSAGE VIA CLIENT - return this.client.sendData(invoke); - } - public replyData(invoke: protocol.Invoke): void - { - invoke.apply(this); // HANDLE INVOKE MESSAGE BY ITSELF - } - } - } - * - * - * - *

        Basic Components

        - *

        What Basic Components are

        - *

        Basic Components are the smallest unit of network communication in this Samchon Framework. With - * Basic Components, you can construct any type of network system, even how the network system is enormously - * scaled and complicated, by just combinating the Basic Components.

        - * - *

        All the system templates in this framework are also being implemented by utilization of the - * Basic Compoonents.

        - * - *
          - *
        • {@link service Service} - *
        • {@link external External System} - *
        • {@link parallel Parallel System} - *
        • {@link distributed Distributed System} - *
        - * - *

        Note that, whatever the network system what you've to construct is, just concentrate on role of each system - * and attach matched Basic Components to the role, within framework of the Object-Oriented Design. - * Then construction of the network system will be much easier.

        - * - *
          - *
        • A system is a server, then use {@link IServer} or {@link IServerBase}.
          • - *
        • A server wants to handle a client has connected, then use {@link IClientDriver}.
          • - *
        • A system is a client connecting to an external server, then use {@link IServerConnector}.
          • - *
          • - *
        - * - *

        Example - System Templates

        - *

        Learning and understanding Basic Components of Samchon Framework, reading source codes and design of - * System Templates' modules will be very helpful.

        - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
        Name Source API Documents
        Cloud Service protocol/service {@link protocol.service}
        External System protocol/external {@link protocol.external}
        Parallel System protocol/parallel {@link protocol.parallel}
        Distributed System protocol/distributed {@link protocol.distributed}
        Slave System protocol/slave {@link protocol.slave}
        - * - *

        Example - Projects

        - * + * * * @see {@link Invoke} - * @handbook Basic Components - IProtocol + * @handbook https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iprotocol * @author Jeongho Nam */ interface IProtocol { /** - *

        Sending message.

        - *

        Sends message to related system or shifts the responsibility to chain.

        + * Sending message. + * + * Sends message to related system or shifts the responsibility to chain. * * @param invoke Invoke message to send */ replyData(invoke: Invoke): void; /** - *

        Handling replied message.

        - *

        Handles replied message or shifts the responsibility to chain.

        + * Handling replied message. + * + * Handles replied message or shifts the responsibility to chain. * * @param invoke An {@link Invoke} message has received. */ @@ -4248,30 +4980,30 @@ declare namespace samchon.protocol { } declare namespace samchon.protocol { /** - *

        Standard message of network I/O.

        + * Standard message of network I/O. * - *

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

        + * {@link 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. + * 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.

        + * network I/O. * - *

        The greatest advantage is that we can make any type of network system, even how the system + * 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.

        + * pattern. * - *

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

        + * classes of S/W architecture. * * @see IProtocol * @author Jeongho Nam */ class Invoke extends EntityArray { /** - *

        Listener, represent function's name.

        + * Listener, represent function's name. */ private listener; /** @@ -4301,13 +5033,13 @@ declare namespace samchon.protocol { */ getListener(): string; /** - *

        Get arguments for Function.apply().

        + * Get arguments for Function.apply(). * * @return An array containing values of the contained parameters. */ getArguments(): Array; /** - *

        Apply to a matched function.

        + * Apply to a matched function. */ apply(obj: IProtocol): boolean; /** @@ -4328,17 +5060,17 @@ declare namespace samchon.protocol { */ class InvokeParameter extends Entity { /** - *

        Name of the parameter.

        + * Name of the parameter. * * @details Optional property, can be omitted. */ protected name: string; /** - *

        Type of the parameter.

        + * Type of the parameter. */ protected type: string; /** - *

        Value of the parameter.

        + * Value of the parameter. */ protected value: string | number | library.XML | Uint8Array; /** @@ -4394,35 +5126,78 @@ declare namespace samchon.protocol { } } declare namespace samchon.protocol { - class InvokeHistory extends Entity { + /** + * History of an {@link Invoke} message. + * + * The {@link InvokeHistory} is a class archiving history log of an {@link Invoke} message with elapsed time. This + * {@link InvokeHistory} class is used to report elapsed time of handling a requested process from **slave** to + * **master** system. + * + * The **master** system utilizes derived {@link InvokeHistory} objects to compute performance indices. + * - {@link ParallelSytem.getPerformance} + * - {@link DistributedProcess.getResource} + * + * @author Jeongho Nam + */ + class InvokeHistory extends protocol.Entity { /** - * + * @hidden */ private uid; /** - * @see {@link Invoke.listener} + * @hidden */ private listener; /** - * + * @hidden */ private start_time_; /** - * + * @hidden */ private end_time_; /** * Default Constructor. */ constructor(); - constructor(invoke: Invoke); + /** + * Construct from an {@link Invoke} message. + * + * @param invoke An {@link Invoke} message requesting a *parallel or distributed process*. + */ + constructor(invoke: protocol.Invoke); + /** + * @inheritdoc + */ construct(xml: library.XML): void; + /** + * Complete the history. + * + * Completes the history and determines the {@link getEndTime end time}. + */ complete(): void; key(): number; + /** + * Get unique ID. + */ getUID(): number; + /** + * Get {@link Invoke.getListener listener} of the {@link Invoke} message. + */ getListener(): string; + /** + * Get start time. + */ getStartTime(): Date; + /** + * Get end time. + */ getEndTime(): Date; + /** + * Compute elapsed time. + * + * @return nanoseconds. + */ computeElapsedTime(): number; /** * @inheritdoc @@ -4432,125 +5207,129 @@ declare namespace samchon.protocol { * @inheritdoc */ toXML(): library.XML; - toInvoke(): Invoke; + /** + * Convert to an {@link Invoke} message. + * + * Creates and returns an {@link Invoke} message that is used to reporting to the **master**. + */ + toInvoke(): protocol.Invoke; } } declare namespace samchon.protocol { /** - *

        An interface for a physical server.

        + * An interface for a server. * - *

        {@link IServer} provides methods for opening a server. Extends one of them who are derived from this - * {@link IServer} and open the server with method {@link open IServer.open()}. Override - * {@link addClient IServer.addClient()} who accepts a newly connected client with {@link IClientDriver}. - * If you're embarrased because your class already extended another one, then use {@link IServerBase}.

        + * {@link IServer} is an interfaec for server classes who are providing methods for {@link open opening a server} and + * {@link IClientDriver accepting clients}. * - *
          - *
        • {@link Server}
          • - *
        • {@link WebServer}
          • - *
        • {@link SharedWorkerServer}
          • - *
        + * To open a server, extends one of derived class under below considedring which protocol to follow first. At next, + * overrides {@link addClient addClient()} method who accepts a newly connected client as an {@link IClientDriver} + * object. Then at last, call {@link open open()} method with specified port number. * - *

        * - *

        + * * - *

        Basic Components

        - *

        What Basic Components are

        - *

        Basic Components are the smallest unit of network communication in this Samchon Framework. With - * Basic Components, you can construct any type of network system, even how the network system is enormously - * scaled and complicated, by just combinating the Basic Components.

        - * - *

        All the system templates in this framework are also being implemented by utilization of the - * Basic Compoonents.

        - * - *
          - *
        • {@link service Service} - *
        • {@link external External System} - *
        • {@link parallel Parallel System} - *
        • {@link distributed Distributed System} - *
        - * - *

        Note that, whatever the network system what you've to construct is, just concentrate on role of each system - * and attach matched Basic Components to the role, within framework of the Object-Oriented Design. - * Then construction of the network system will be much easier.

        - * - *
          - *
        • A system is a server, then use {@link IServer} or {@link IServerBase}.
          • - *
        • A server wants to handle a client has connected, then use {@link IClientDriver}.
          • - *
        • A system is a client connecting to an external server, then use {@link IServerConnector}.
          • - *
          • - *
        - * - *

        Example - System Templates

        - *

        Learning and understanding Basic Components of Samchon Framework, reading source codes and design of - * System Templates' modules will be very helpful.

        - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
        Name Source API Documents
        Cloud Service protocol/service {@link protocol.service}
        External System protocol/external {@link protocol.external}
        Parallel System protocol/parallel {@link protocol.parallel}
        Distributed System protocol/distributed {@link protocol.distributed}
        Slave System protocol/slave {@link protocol.slave}
        - * - *

        Example - Projects

        - * - * - * @see {@link IClientDriver} - * @handbook Basic Components - IServer + * @see {@link IClientDriver}, {@link IServerBase} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserver) * @author Jeongho Nam */ interface IServer { + /** + * Open server. + * + * @param port Port number to open. + */ open(port: number): void; + /** + * Close server. + * + * Close opened server. All remote clients, have connected with this server, are also closed and their call back + * functions, for closed connection, {@link IClientDriver.onClose} are also called. + */ close(): void; - addClient(clientDriver: IClientDriver): void; + /** + * Add a newly connected remote client. + * + * The {@link addClient addClient()} is an abstract method being called when a remote client is newly connected + * with {@link IClientDriver} object who communicates with the remote system. Overrides this method and defines + * what to do with the *driver*, a newly connected remote client. + * + * Below methods and example codes may be good for comprehending how to utilize this {@link addClient} method. + * + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * - https://github.com/samchon/framework/blob/master/ts/examples/chat-server/server.ts + * - {@link service.Server.addClient} + * - {@link external.ExternalClientArray.addClient} + * - {@link slave.SlaveServer.addClient} + * + * @param driver A {@link ICommunicator communicator} with (newly connected) remote client. + */ + addClient(driver: IClientDriver): void; } } declare namespace samchon.protocol { + /** + * A server. + * + * The {@link Server} is an abstract class designed to open a server and accept clients who are following Samchon + * Framework's own protocol. Extends this {@link Server} class and overrides {@link addClient addClient()} method to + * define what to do with newly connected {@link ClientDriver remote clients}. + * + * #### [Inherited] {@link IServer} + * {@link IServer} is an interfaec for server classes who are providing methods for {@link open opening a server} and + * {@link IClientDriver accepting clients}. + * + * To open a server, extends one of derived class under below considedring which protocol to follow first. At next, + * overrides {@link addClient addClient()} method who accepts a newly connected client as an {@link IClientDriver} + * object. Then at last, call {@link open open()} method with specified port number. + * + * Protocol | Derived Type | Related {@link IClientDriver} + * ---------|--------------|------------------------------- + * Samchon Framework's own | {@link Server} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerClientDriver} + * + * Below codes and classes will be good examples for comprehending how to open a server and handle remote clients. + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * - https://github.com/samchon/framework/blob/master/ts/examples/chat-server/server.ts + * - {@link service.Server} + * - {@link external.ExternalClientArray} + * - {@link slave.SlaveServer} + * + * If you're embarrased because your class already extended another one, then use {@link IServerBase}. + * + * + * + * + * + * @see {@link ClientDriver}, {@link ServerBase} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserver) + * @author Jeongho Nam + */ abstract class Server implements IServer { + /** + * @hidden + */ private server; /** * @inheritdoc @@ -4564,17 +5343,60 @@ declare namespace samchon.protocol { * @inheritdoc */ close(): void; + /** + * @hidden + */ private handle_connect(socket); } } declare namespace samchon.protocol { + /** + * A web server. + * + * The {@link WebServer} is an abstract class designed to open a server and accept clients who are following + * web-socket protocol. Extends this {@link WebServer} class and overrides {@link addClient addClient()} method to + * define what to do with newly connected {@link WebClientDriver remote clients}. + * + * #### [Inherited] {@link IServer} + * {@link IServer} is an interfaec for server classes who are providing methods for {@link open opening a server} and + * {@link IClientDriver accepting clients}. + * + * To open a server, extends one of derived class under below considedring which protocol to follow first. At next, + * overrides {@link addClient addClient()} method who accepts a newly connected client as an {@link IClientDriver} + * object. Then at last, call {@link open open()} method with specified port number. + * + * Protocol | Derived Type | Related {@link IClientDriver} + * ---------|--------------|------------------------------- + * Samchon Framework's own | {@link Server} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerClientDriver} + * + * Below codes and classes will be good examples for comprehending how to open a server and handle remote clients. + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * - https://github.com/samchon/framework/blob/master/ts/examples/chat-server/server.ts + * - {@link service.Server} + * - {@link external.ExternalClientArray} + * - {@link slave.SlaveServer} + * + * If you're embarrased because your class already extended another one, then use {@link IServerBase}. + * + * + * + * + * + * @see {@link WebClientDriver}, {@link WebServerBase} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserver) + * @author Jeongho Nam + */ abstract class WebServer implements IServer { /** - * A server handler. + * @hidden */ private http_server_; /** - * Sequence number for issuing session id. + * @hidden */ private sequence_; /** @@ -4598,31 +5420,70 @@ declare namespace samchon.protocol { */ abstract addClient(driver: WebClientDriver): void; /** - *

        Handle request from a client system.

        - * - *

        This method {@link handle_request} will be called when a client is connected. It will call an abstract - * method method {@link addClient addClient()} who handles an accepted client. If the newly connected client - * doesn't have its own session id, then a new session id will be issued.

        - * - * @param request Requested header. + * @hidden */ private handle_request(request); /** - *

        Get session id from a newly connected.

        - * - *

        Queries ordinary session id from cookies of a newly connected client. If the client has not, a new - * session id will be issued.

        - * - * @param cookies Cookies from the remote client. + * @hidden */ private get_session_id(cookies); /** - * Issue a new session id. + * @hidden */ private issue_session_id(); } } declare namespace samchon.protocol { + /** + * A SharedWorker server. + * + * The {@link SharedWorker} is an abstract class is realized to open a SharedWorker server and accept web-browser + * clients. Extends this {@link SharedWorkerServer} class and overrides {@link addClient addClient()} method to + * define what to do with newly connected {@link ClientDriver remote clients}. + * + * #### Why SharedWorker be a server? + * SharedWorker, it allows only an instance (process) to be created whether the SharedWorker is declared in a browser + * or multiple browsers. To integrate them, messages are being sent and received. Doesn't it seem like a relationship + * between a server and clients? Thus, Samchon Framework consider the SharedWorker as a server and browsers as + * clients. + * + * The class {@link SharedWorkerCommunicator} is designed make such relationship. From now on, SharedWorker is a + * {@link SharedWorkerServer server} and {@link SharedWorkerServerConnector browsers} are clients. Integrate the + * server and clients with this {@link SharedWorkerCommunicator}. + * + * #### [Inherited] {@link IServer} + * {@link IServer} is an interfaec for server classes who are providing methods for {@link open opening a server} and + * {@link IClientDriver accepting clients}. + * + * To open a server, extends one of derived class under below considedring which protocol to follow first. At next, + * overrides {@link addClient addClient()} method who accepts a newly connected client as an {@link IClientDriver} + * object. Then at last, call {@link open open()} method with specified port number. + * + * Protocol | Derived Type | Related {@link IClientDriver} + * ---------|--------------|------------------------------- + * Samchon Framework's own | {@link Server} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerClientDriver} + * + * Below codes and classes will be good examples for comprehending how to open a server and handle remote clients. + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-server.ts + * - https://github.com/samchon/framework/blob/master/ts/examples/chat-server/server.ts + * - {@link service.Server} + * - {@link external.ExternalClientArray} + * - {@link slave.SlaveServer} + * + * If you're embarrased because your class already extended another one, then use {@link IServerBase}. + * + * + * + * + * + * @see {@link SharedWorkerClientDriver}, {@link SharedWorkerServerBase} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserver) + * @author Jeongho Nam + */ abstract class SharedWorkerServer implements IServer { /** * @inheritdoc @@ -4636,57 +5497,56 @@ declare namespace samchon.protocol { * @inheritdoc */ close(): void; + /** + * @hidden + */ private handle_connect(event); } } declare namespace samchon.protocol { /** - *

        An interface for substitute server classes.

        + * An interface for substitute server classes. * - *

        {@link IServerBase} is an interface for substitue server classes who subrogate server's role.

        + * {@link IServerBase} is an interface for substitue server classes who subrogate server's role. * - *

        The easiest way to defining a server class is to extending one of them, who are derived from the - * {@link IServer}.

        + * The easiest way to defining a server class is to extending one of them below, who implemented the {@link IServer}. + * However, it is impossible (that is, if the class is already extending another class), you can instead implement + * the {@link IServer} interface, create an {@link IServerBase} member, and write simple hooks to route calls into + * the aggregated {@link IServerBase}. * - *
          - *
        • {@link Server}
          • - *
        • {@link WebServer}
          • - *
        • {@link SharedWorkerServer}
          • - *
        + * Protocol | {@link IServer} | {@link IServerBase} | {@link IClientDriver} + * ---------|-----------------|---------------------|----------------------- + * Samchon Framework's own | {@link Server} | {@link ServerBase} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebServerBase} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerServerBase} | {@link SharedWorkerClientDriver} * - *

        However, it is impossible (that is, if the class is already extending another class), you can instead implement - * the {@link IServer} interface, create an {@link IServerBase} member, and write simple hooks to route calls into the - * aggregated {@link IServerBase}.

        + * After the hooking to aggregated {@link IServerBase} object, overrides {@link addClient addClient()} method who + * accepts a newly connected client as an {@link IClientDriver} object. At last, call {@link open open()} method with + * specified port number. * - *

        {@link ExternalClientArray} can be a good example using this {@link IServerBase}.

        - *
          - *
        • https://github.com/samchon/framework/blob/master/ts/src/samchon/protocol/external/ExternalClientArray.ts
          • - *
        + * ```typescript + * class MyServer extends Something implements IServer + * { + * private server_base_: IServerBase = new WebServerBase(this); * - * - class MyServer extends Something implements IServer - { - private server_base: IServerBase = new WebServerBase(this); - - public addClient(driver: IClientDriver): void - { - // WHAT TO DO WHEN A CLIENT HAS CONNECTED - } - - public open(port: number): void - { - this.server_base.open(); - } - public close(): void - { - this.server_base.close(); - } - } - * + * public addClient(driver: IClientDriver): void + * { + * // WHAT TO DO WHEN A CLIENT HAS CONNECTED + * } * - * @see {@link IServer} - * @handbook Basic Components - IServerBase + * public open(port: number): void + * { + * this.server_base_.open(); + * } + * public close(): void + * { + * this.server_base_.close(); + * } + * } + * ``` + * + * @see {@link IServer}, {@link IClientDriver} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverbase) * @author Jeongho Nam */ interface IServerBase extends IServer { @@ -4694,172 +5554,257 @@ declare namespace samchon.protocol { } declare namespace samchon.protocol { /** - *

        A substitute {@link Server}.

        + * A substitute {@link Server}. * - *

        {@link ServerBase} is a substitute class who subrogates {@link Server}'s responsibility.

        + * The {@link ServerBase} is a substitute class who subrogates {@link Server}'s responsibility. * - *

        The easiest way to defning a server class following normal protocol of Samchon Framework is to extending - * {@link Server}. However, it is impossible (that is, if the class is already extending another class), you can - * instead implement the {@link IServer} interface, create a {@link ServerBase} member, and write simple hooks - * to route calls into the aggregated {@link ServerBase}.

        + * #### [Inherited] {@link IServerBase} + * {@link IServerBase} is an interface for substitue server classes who subrogate server's role. * - *

        {@link ExternalClientArray} can be a good example using this {@link IServerBase}.

        - *
          - *
        • https://github.com/samchon/framework/blob/master/ts/src/samchon/protocol/external/ExternalClientArray.ts
          • - *
        + * The easiest way to defining a server class is to extending one of them below, who implemented the {@link IServer}. + * However, it is impossible (that is, if the class is already extending another class), you can instead implement + * the {@link IServer} interface, create an {@link IServerBase} member, and write simple hooks to route calls into + * the aggregated {@link IServerBase}. * - * - class MyServer extends Something implements IServer - { - private server_base: ServerBase = new ServerBase(this); - - public addClient(driver: ClientDriver): void - { - // WHAT TO DO WHEN A CLIENT HAS CONNECTED - } - - public open(port: number): void - { - this.server_base.open(); - } - public close(): void - { - this.server_base.close(); - } - } - * + * Protocol | {@link IServer} | {@link IServerBase} | {@link IClientDriver} + * ---------|-----------------|---------------------|----------------------- + * Samchon Framework's own | {@link Server} | {@link ServerBase} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebServerBase} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerServerBase} | {@link SharedWorkerClientDriver} * + * After the hooking to aggregated {@link IServerBase} object, overrides {@link addClient addClient()} method who + * accepts a newly connected client as an {@link IClientDriver} object. At last, call {@link open open()} method with + * specified port number. + * + * ```typescript + * class MyServer extends Something implements IServer + * { + * private server_base_: IServerBase = new WebServerBase(this); + * + * public addClient(driver: IClientDriver): void + * { + * // WHAT TO DO WHEN A CLIENT HAS CONNECTED + * } + * + * public open(port: number): void + * { + * this.server_base_.open(); + * } + * public close(): void + * { + * this.server_base_.close(); + * } + * } + * ``` + * + * @see {@link Server}, {@link ClientDriver} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverbase) * @author Jeongho Nam */ class ServerBase extends Server implements IServerBase { - private target_; - constructor(target: IServer); + /** + * @hidden + */ + private hooker_; + /** + * Construct from a *hooker*. + * + * @param hooker A hooker throwing responsibility of server's role. + */ + constructor(hooker: IServer); + /** + * @inheritdoc + */ addClient(driver: IClientDriver): void; } } declare namespace samchon.protocol { /** - *

        A substitute {@link WebServer}.

        + * A substitute {@link WebServer}. * - *

        {@link WebServerBase} is a substitute class who subrogates {@link WebServer}'s responsibility.

        + * The {@link WebServerBase} is a substitute class who subrogates {@link WebServer}'s responsibility. * - *

        The easiest way to defning a server class following normal protocol of Samchon Framework is to extending - * {@link WebServer}. However, it is impossible (that is, if the class is already extending another class), you can - * instead implement the {@link IServer} interface, create a {@link WebServerBase} member, and write simple hooks to - * route calls into the aggregated {@link WebServerBase}.

        + * {@link IServerBase} is an interface for substitue server classes who subrogate server's role. * - *

        {@link ExternalClientArray} can be a good example using this {@link IServerBase}.

        - *
          - *
        • https://github.com/samchon/framework/blob/master/ts/src/samchon/protocol/external/ExternalClientArray.ts
          • - *
        + * The easiest way to defining a server class is to extending one of them below, who implemented the {@link IServer}. + * However, it is impossible (that is, if the class is already extending another class), you can instead implement + * the {@link IServer} interface, create an {@link IServerBase} member, and write simple hooks to route calls into + * the aggregated {@link IServerBase}. * - * - class MyServer extends Something implements IServer - { - private server_base: WebServerBase = new WebServerBase(this); - - public addClient(driver: WebClientDriver): void - { - // WHAT TO DO WHEN A CLIENT HAS CONNECTED - } - - public open(port: number): void - { - this.server_base.open(); - } - public close(): void - { - this.server_base.close(); - } - } - * + * Protocol | {@link IServer} | {@link IServerBase} | {@link IClientDriver} + * ---------|-----------------|---------------------|----------------------- + * Samchon Framework's own | {@link Server} | {@link ServerBase} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebServerBase} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerServerBase} | {@link SharedWorkerClientDriver} * + * After the hooking to aggregated {@link IServerBase} object, overrides {@link addClient addClient()} method who + * accepts a newly connected client as an {@link IClientDriver} object. At last, call {@link open open()} method with + * specified port number. + * + * ```typescript + * class MyServer extends Something implements IServer + * { + * private server_base_: IServerBase = new WebServerBase(this); + * + * public addClient(driver: IClientDriver): void + * { + * // WHAT TO DO WHEN A CLIENT HAS CONNECTED + * } + * + * public open(port: number): void + * { + * this.server_base_.open(); + * } + * public close(): void + * { + * this.server_base_.close(); + * } + * } + * ``` + * + * @see {@link WebServer}, {@link WebClientDriver} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverbase) * @author Jeongho Nam */ class WebServerBase extends WebServer implements IServerBase { - private target_; - constructor(target: IServer); + /** + * @hidden + */ + private hooker_; + /** + * Construct from a *hooker*. + * + * @param hooker A hooker throwing responsibility of server's role. + */ + constructor(hooker: IServer); + /** + * @inheritdoc + */ addClient(driver: IClientDriver): void; } } declare namespace samchon.protocol { /** - *

        A substitute {@link SharedWorkerServer}.

        + * A substitute {@link SharedWorkerServer}. * - *

        {@link SharedWorkerServerBase} is a substitute class who subrogates {@link SharedWorkerServer}'s - * responsibility.

        + * The {@link SharedWorkerServerBase} is a substitute class who subrogates {@link SharedWorkerServer}'s + * responsibility. * - *

        The easiest way to defning a server class following normal protocol of Samchon Framework is to extending - * {@link SharedWorkerServer}. However, it is impossible (that is, if the class is already extending another class), - * you can instead implement the {@link IServer} interface, create a {@link SharedWorkerServerBase} member, and write - * simple hooks to route calls into the aggregated {@link SharedWorkerServerBase}.

        + * {@link IServerBase} is an interface for substitue server classes who subrogate server's role. * - *

        {@link ExternalClientArray} can be a good example using this {@link IServerBase}.

        - *
          - *
        • https://github.com/samchon/framework/blob/master/ts/src/samchon/protocol/external/ExternalClientArray.ts
          • - *
        + * The easiest way to defining a server class is to extending one of them below, who implemented the {@link IServer}. + * However, it is impossible (that is, if the class is already extending another class), you can instead implement + * the {@link IServer} interface, create an {@link IServerBase} member, and write simple hooks to route calls into + * the aggregated {@link IServerBase}. * - * - class MyServer extends Something implements IServer - { - private server_base: SharedWorkerServerBase = new SharedWorkerServerBase(this); - - public addClient(driver: SharedWorkerClientDriver): void - { - // WHAT TO DO WHEN A CLIENT HAS CONNECTED - } - - public open(port: number): void - { - this.server_base.open(); - } - public close(): void - { - this.server_base.close(); - } - } - * + * Protocol | {@link IServer} | {@link IServerBase} | {@link IClientDriver} + * ---------|-----------------|---------------------|----------------------- + * Samchon Framework's own | {@link Server} | {@link ServerBase} | {@link ClientDriver} + * Web-socket protocol | {@link WebServer} | {@link WebServerBase} | {@link WebClientDriver} + * SharedWorker | {@link SharedWorkerServer} | {@link SharedWorkerServerBase} | {@link SharedWorkerClientDriver} * + * After the hooking to aggregated {@link IServerBase} object, overrides {@link addClient addClient()} method who + * accepts a newly connected client as an {@link IClientDriver} object. At last, call {@link open open()} method with + * specified port number. + * + * ```typescript + * class MyServer extends Something implements IServer + * { + * private server_base_: IServerBase = new WebServerBase(this); + * + * public addClient(driver: IClientDriver): void + * { + * // WHAT TO DO WHEN A CLIENT HAS CONNECTED + * } + * + * public open(port: number): void + * { + * this.server_base_.open(); + * } + * public close(): void + * { + * this.server_base_.close(); + * } + * } + * ``` + * + * @see {@link SharedWorkerServer}, {@link SharedWorkerClientDriver} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverbase) * @author Jeongho Nam */ class SharedWorkerServerBase extends SharedWorkerServer implements IServerBase { - private target_; - constructor(target: IServer); + /** + * @hidden + */ + private hooker_; + /** + * Construct from a *hooker*. + * + * @param hooker A hooker throwing responsibility of server's role. + */ + constructor(hooker: IServer); + /** + * @inheritdoc + */ addClient(driver: IClientDriver): void; } } declare namespace samchon.protocol { /** - *

        An interface for server connector.

        + * An interface for server connector. * - *

        {@link IServerConnector} is an interface for server connector classes who ca connect to an external server - * as a client.

        + * {@link IServerConnector} is a type of {@link ICommunicator}, specified for server connector classes who connect to + * the remote server as a client. {@link IServerConnector} provides {@link connect connection method} and takes full + * charge of network communication with the remote server. * - *

        Of course, {@link IServerConnector} is extended from the {@link ICommunicator}, thus, it also takes full - * charge of network communication and delivers replied message to {@link WebCommunicator.listener listener}'s - * {@link IProtocol.replyData replyData()} method.

        + * Declare specific type of {@link IServerConnector} from {@link IProtocol listener} and call the + * {@link connect connect()} method. Then whenever a replied message comes from the remote system, the message will + * be converted to an {@link Invoke} object and the {@link Invoke} object will be shifted to the + * {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. Below code is an example + * connecting to remote server and interacting with it. * - * @handbook Basic Components - IServerConnector + * - https://github.com/samchon/framework/blob/master/ts/examples/calculator/calculator-application.ts + * + * Note that, protocol of this client and remote server must be matched. Thus, before determining specific type of + * this {@link IServerConnector}, you've to consider which protocol and type the remote server follows. + * + * Protocol | Derived Type | Connect to + * ---------|--------------|--------------- + * Samchon Framework's own | {@link ServerConnector} | {@link Server} + * Web-socket protocol | {@link WebServerConnector} | {@link WebServer} + * SharedWorker | {@link SharedWorkerServerConnector} | {@link SharedWorkerServer} + * + * + * + * + * + * @see {@link IServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverconnector) * @author Jeongho Nam */ interface IServerConnector extends ICommunicator { /** * Callback function for connection completed. + * + * When you call {@link connect connect()} and the connection has completed, then this call back function + * {@link onConnect} will be called. Note that, if the listener of this {@link onConnect} is a member method of + * some class, then you've use the ```bind```. */ onConnect: Function; /** - *

        Connect to a server.

        + * Connect to a server. * - *

        Connects to a server with specified host address and port number. After the connection has + * Connects to a server with specified *host* address and *port* number. After the connection has * succeeded, callback function {@link onConnect} is called. Listening data from the connected server also begins. * Replied messages from the connected server will be converted to {@link Invoke} classes and will be shifted to - * the {@link WebCommunicator.listener listener}'s {@link IProtocol.replyData replyData()} method.

        + * the {@link WebCommunicator.listener listener}'s {@link IProtocol.replyData replyData()} method. * - *

        If the connection fails immediately, either an event is dispatched or an exception is thrown: an error + * If the connection fails immediately, either an event is dispatched or an exception is thrown: an error * event is dispatched if a host was specified, and an exception is thrown if no host was specified. Otherwise, * the status of the connection is reported by an event. If the socket is already connected, the existing - * connection is closed first.

        + * connection is closed first. * * @param ip The name or IP address of the host to connect to. * If no host is specified, the host that is contacted is the host where the calling file resides. @@ -4871,45 +5816,140 @@ declare namespace samchon.protocol { } } declare namespace samchon.protocol { + /** + * Server connnector. + * + * {@link ServerConnector} is a class connecting to remote server who follows Samchon Framework's own protocol and + * taking full charge of network communication with the remote server. Create a {@link ServerConnector} instance from + * the {@IProtocol listener} and call the {@link connect connect()} method. + * + * #### [Inherited] {@link IServerConnector} + * {@link IServerConnector} is a type of {@link ICommunicator}, specified for server connector classes who connect to + * the remote server as a client. {@link IServerConnector} provides {@link connect connection method} and takes full + * charge of network communication with the remote server. + * + * Declare specific type of {@link IServerConnector} from {@link IProtocol listener} and call the + * {@link connect connect()} method. Then whenever a replied message comes from the remote system, the message will + * be converted to an {@link Invoke} object and the {@link Invoke} object will be shifted to the + * {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * + * Note that, protocol of this client and remote server must be matched. Thus, before determining specific type of + * this {@link IServerConnector}, you've to consider which protocol and type the remote server follows. + * + * Protocol | Derived Type | Connect to + * ---------|--------------|--------------- + * Samchon Framework's own | {@link ServerConnector} | {@link Server} + * Web-socket protocol | {@link WebServerConnector} | {@link WebServer} + * SharedWorker | {@link SharedWorkerServerConnector} | {@link SharedWorkerServer} + * + * + * + * + * + * @see {@link Server}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverconnector) + * @author Jeongho Nam + */ class ServerConnector extends Communicator implements IServerConnector { /** * @inheritdoc */ onConnect: Function; + /** + * Construct from *listener*. + * + * @param listener A listener object to listen replied message from newly connected client in + * {@link IProtocol.replyData replyData()} as an {@link Invoke} object. + */ constructor(listener: IProtocol); /** * @inheritdoc */ connect(ip: string, port: number): void; + /** + * @hidden + */ private handle_connect(...arg); } } declare namespace samchon.protocol { /** - *

        A server connector for web-socket protocol.

        + * A server connector for web-socket protocol. * + * {@link WebServerConnector} is a class connecting to remote server who follows Web-socket protocol and taking full + * charge of network communication with the remote server. Create an {@link WebServerConnector} instance from the + * {@IProtocol listener} and call the {@link connect connect()} method. + * + * #### [Inherited] {@link IServerConnector} + * {@link IServerConnector} is a type of {@link ICommunicator}, specified for server connector classes who connect to + * the remote server as a client. {@link IServerConnector} provides {@link connect connection method} and takes full + * charge of network communication with the remote server. + * + * Declare specific type of {@link IServerConnector} from {@link IProtocol listener} and call the + * {@link connect connect()} method. Then whenever a replied message comes from the remote system, the message will + * be converted to an {@link Invoke} class and the {@link Invoke} object will be shifted to the + * {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * + * Note that, protocol of this client and remote server must be matched. Thus, before determining specific type of + * this {@link IServerConnector}, you've to consider which protocol and type the remote server follows. + * + * Protocol | Derived Type | Connect to + * ---------|--------------|--------------- + * Samchon Framework's own | {@link ServerConnector} | {@link Server} + * Web-socket protocol | {@link WebServerConnector} | {@link WebServer} + * SharedWorker | {@link SharedWorkerServerConnector} | {@link SharedWorkerServer} + * + * + * + * + * + * @see {@link WebServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverconnector) * @author Jeongho Nam */ class WebServerConnector extends WebCommunicator implements IServerConnector { /** - *

        A socket for network I/O.

        - * - *

        Note that, {@link socket} is only used in web-browser environment.

        + * @hidden */ private browser_socket_; /** - *

        A driver for server connection.

        - * - *

        Note that, {@link node_client} is only used in NodeJS environment.

        + * @hidden */ private node_client_; /** * @inheritdoc */ onConnect: Function; + /** + * Construct from *listener*. + * + * @param listener A listener object to listen replied message from newly connected client in + * {@link IProtocol.replyData replyData()} as an {@link Invoke} object. + */ constructor(listener: IProtocol); /** - * @inheritdoc + * Connect to a web server. + * + * Connects to a server with specified *host* address, *port* number and *path*. After the connection has + * succeeded, callback function {@link onConnect} is called. Listening data from the connected server also begins. + * Replied messages from the connected server will be converted to {@link Invoke} classes and will be shifted to + * the {@link WebCommunicator.listener listener}'s {@link IProtocol.replyData replyData()} method. + * + * If the connection fails immediately, either an event is dispatched or an exception is thrown: an error + * event is dispatched if a host was specified, and an exception is thrown if no host was specified. Otherwise, + * the status of the connection is reported by an event. If the socket is already connected, the existing + * connection is closed first. + * + * @param ip The name or IP address of the host to connect to. + * If no host is specified, the host that is contacted is the host where the calling file resides. + * If you do not specify a host, use an event listener to determine whether the connection was + * successful. + * @param port The port number to connect to. + * @param path Path of service which you want. */ connect(ip: string, port: number, path?: string): void; /** @@ -4920,18 +5960,96 @@ declare namespace samchon.protocol { * @inheritdoc */ sendData(invoke: Invoke): void; + /** + * @hidden + */ private handle_browser_connect(event); + /** + * @hidden + */ private handle_browser_message(event); + /** + * @hidden + */ private handle_node_connect(connection); } } declare namespace samchon.protocol { + /** + * A server connector for SharedWorker. + * + * {@link SharedWorkerServerConnector} is a class connecting to SharedWorker and taking full charge of network + * communication with the SharedWorker. Create an {@link SharedWorkerServerConnector} instance from the + * {@IProtocol listener} and call the {@link connect connect()} method. + * + * #### Why SharedWorker be a server? + * SharedWorker, it allows only an instance (process) to be created whether the SharedWorker is declared in a browser + * or multiple browsers. To integrate them, messages are being sent and received. Doesn't it seem like a relationship + * between a server and clients? Thus, Samchon Framework consider the SharedWorker as a server and browsers as + * clients. + * + * The class {@link SharedWorkerCommunicator} is designed make such relationship. From now on, SharedWorker is a + * {@link SharedWorkerServer server} and {@link SharedWorkerServerConnector browsers} are clients. Integrate the + * server and clients with this {@link SharedWorkerCommunicator}. + * + * #### [Inherited] {@link IServerConnector} + * {@link IServerConnector} is a type of {@link ICommunicator}, specified for server connector classes who connect to + * the remote server as a client. {@link IServerConnector} provides {@link connect connection method} and takes full + * charge of network communication with the remote server. + * + * Declare specific type of {@link IServerConnector} from {@link IProtocol listener} and call the + * {@link connect connect()} method. Then whenever a replied message comes from the remote system, the message will + * be converted to an {@link Invoke} class and the {@link Invoke} object will be shifted to the + * {@link IProtocol listener}'s {@link IProtocol.replyData IProtocol.replyData()} method. + * + * Note that, protocol of this client and remote server must be matched. Thus, before determining specific type of + * this {@link IServerConnector}, you've to consider which protocol and type the remote server follows. + * + * Protocol | Derived Type | Connect to + * ---------|--------------|--------------- + * Samchon Framework's own | {@link ServerConnector} | {@link Server} + * Web-socket protocol | {@link WebServerConnector} | {@link WebServer} + * SharedWorker | {@link SharedWorkerServerConnector} | {@link SharedWorkerServer} + * + * + * + * + * + * @see {@link SharedWorkerServer}, {@link IProtocol} + * @handbook [Protocol - Basic Components](https://github.com/samchon/framework/wiki/TypeScript-Protocol-Basic_Components#iserverconnector) + * @author Jeongho Nam + */ class SharedWorkerServerConnector extends SharedWorkerCommunicator implements IServerConnector { /** * @inheritdoc */ onConnect: Function; + /** + * Construct from *listener*. + * + * @param listener A listener object to listen replied message from newly connected client in + * {@link IProtocol.replyData replyData()} as an {@link Invoke} object. + */ constructor(listener: IProtocol); + /** + * Connect to a SharedWorker. + * + * Connects to a server with specified *jstFile* path. If a SharedWorker instance of the *jsFile* is not + * constructed yet, then the SharedWorker will be newly constructed. Otherwise the SharedWorker already exists, + * then connect to the SharedWorker. After those processes, callback function {@link onConnect} is called. + * Listening data from the connected server also begins. Replied messages from the connected server will be + * converted to {@link Invoke} classes and will be shifted to the {@link WebCommunicator.listener listener}'s + * {@link IProtocol.replyData replyData()} method. + * + * If the connection fails immediately, either an event is dispatched or an exception is thrown: an error + * event is dispatched if a host was specified, and an exception is thrown if no host was specified. Otherwise, + * the status of the connection is reported by an event. If the socket is already connected, the existing + * connection is closed first. + * + * @param jsFile Path of JavaScript file to execute who defines SharedWorker. + */ connect(jsFile: string): void; } } @@ -4955,57 +6073,130 @@ declare namespace samchon.protocol { type client = any; } } -declare namespace samchon.protocol.distributed { - class DSInvokeHistory extends InvokeHistory { +declare namespace samchon.templates.distributed { + /** + * History of an {@link Invoke} message. + * + * The {@link PRInvokeHistory} is a class archiving history log of an {@link Invoke} message which requests the + * *distributed process*, created whenever {@link DistributedProcess.sendData} is called. + * + * When the *distributed process* has completed, then {@link complete complete()} is called and the *elapsed time* is + * determined. The elapsed time is utilized for computation of {@link DistributedSystem.getPerformance performance index} + * and {@link DistributedProcess.getResource resource index} of related objects. + * + * + * + * + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class DSInvokeHistory extends protocol.InvokeHistory { + /** + * @hidden + */ private system_; - private role_; + /** + * @hidden + */ + private process_; /** * Construct from a DistributedSystem. * - * @param system + * @param system The {@link DistributedSystem} object who sent the {@link Invoke} message. */ constructor(system: DistributedSystem); /** * Initilizer Constructor. * - * @param system - * @param role - * @param invoke + * @param system The {@link DistributedSystem} object who sent the {@link Invoke} message. + * @param process The {@link DistributedProcess} object who sent the {@link Invoke} message. + * @param invoke An {@link Invoke} message requesting the *distributed process*. */ - constructor(system: DistributedSystem, role: DistributedSystemRole, invoke: Invoke); + constructor(system: DistributedSystem, process: DistributedProcess, invoke: protocol.Invoke); /** * @inheritdoc */ construct(xml: library.XML): void; + /** + * Get the related {@link DistributedSystem} object. + */ getSystem(): DistributedSystem; - getRole(): DistributedSystemRole; + /** + * Get the related {@link DistributedProcess} object. + */ + getProcess(): DistributedProcess; /** * @inheritdoc */ toXML(): library.XML; } } -declare namespace samchon.protocol.external { +declare namespace samchon.templates.distributed { /** - *

        A role of an external system.

        + * Master of Distributed Processing System, a server accepting slave clients. * - *

        The {@link ExternalSystemRole} class represents a role, what to do in an {@link ExternalSystem}. - * Extends this class and writes some methods related to the role.

        + * The {@link DistributedClientArray} is an abstract class, derived from the {@link DistributedSystemArray} class, + * opening a server accepting {@link DistributedSystem distributed clients}. * - *

        - * - *

        + * * - *

        Proxy Pattern

        - *

        The {@link ExternalSystemRole} class can be an logical proxy. In framework within user, which + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        + * important. Only interested in user's perspective is *which can be done*. * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. * *
          *
        • @@ -5017,20 +6208,1977 @@ declare namespace samchon.protocol.external { * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the * external system. *
          • - *
        • Those strategy is called Proxy Pattern.
          • + *
        • Those strategy is called *Proxy Pattern*.
          • *
        * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) * @author Jeongho Nam */ - abstract class ExternalSystemRole extends Entity implements IProtocol { + abstract class DistributedClientArray extends DistributedSystemArray implements external.IExternalClientArray { /** - * An {@link ExternalSystem external system} containing this {@link ExternalSystemRole role}. + * @hidden + */ + private server_base_; + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method creating {@link IServerBase} object. + * + * This method {@link createServerBase createServerBase()} determines which protocol is used in this server, + * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who + * may connect to {@link ExternalClientArray this server} must follow the specified protocol. + * + * Overrides the {@link createServerBase createServerBase()} method to create and return one of them: + * + * - {@link ServerBase} + * - {@link WebServerBase} + * - {@link SharedWorkerServerBase} + * + * @return A new {@link IServerBase} object. + */ + protected abstract createServerBase(): protocol.IServerBase; + /** + * Add a newly connected remote client. + * + * When a {@link IClientDriver remote client} connects to this *master server of parallel processing system*, + * then this {@link ParallelClientArray} creates a child {@link ParallelSystem parallel client} object through + * the {@link createExternalClient createExternalClient()} method and {@link insert inserts} it. + * + * @param driver A communicator for external client. + */ + addClient(driver: protocol.IClientDriver): void; + /** + * (Deprecated) Factory method creating child object. + * + * The method {@link createChild createChild()} is deprecated. Don't use and override this. + * + * Note that, the {@link ParallelClientArray} is a server accepting {@link ParallelSystem parallel clients}. + * There's no way to creating the {@link ParallelSystem parallel clients} in advance before opening the server. + * + * @param xml An {@link XML} object represents the child {@link ParallelSystem} object. + * @return ```null``` + */ + createChild(xml: library.XML): DistributedSystem; + /** + * Factory method creating {@link DistributedSystem} object. + * + * The method {@link createExternalClient createExternalClient()} is a factory method creating a child + * {@link ParallelSystem} object, that is called whenever a parallel client has connected, by + * {@link addClient addClient()}. + * + * Overrides this {@link createExternalClient} method and creates a type of {@link DistributedSystem} object with + * the *driver* that communicates with the parallel client. After the creation, returns the object. Then whenever + * a parallel client has connected, matched {@link DistributedSystem} object will be constructed and + * {@link insert inserted} into this {@link DistributedSystemArray} object. + * + * @param driver A communicator with the parallel client. + * @return A newly created {@link ParallelSystem} object. + */ + protected abstract createExternalClient(driver: protocol.IClientDriver): DistributedSystem; + /** + * @inheritdoc + */ + open(port: number): void; + /** + * @inheritdoc + */ + close(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * Mediator of Distributed Processing System, a server accepting slave clients. + * + * The {@link DistributedClientArrayMediator} is an abstract class, derived from {@link DistributedSystemArrayMediator} + * class, opening a server accepting {@link DistributedSystem distributed clients} as a **master**. + * + * Extends this {@link DistributedClientArrayMediator}, overrides {@link createServerBase createServerBase()} to + * determine which protocol to follow and {@link createExternalClient createExternalClient()} creating child + * {@link DistributedSystem} object. After the extending and overridings, open this server using the + * {@link open open()} method. + * + * #### [Inherited] {@link DistributedSystemArrayMediator} + * The {@link DistributedSystemArrayMediator} class be a master for its slave systems, and be a slave to its master + * system at the same time. This {@link DistributedSystemArrayMediator} be a master system, containing and managing + * {@link DistributedSystem} objects, which represent distributed slave systems, by extending + * {@link DistributedSystemArray} class. Also, be a slave system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a slave, you can specify this {@link DistributedSystemArrayMediator} to be a client slave connecting to master + * server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedClientArrayMediator extends DistributedSystemArrayMediator implements external.IExternalClientArray { + /** + * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. + */ + private server_base_; + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method creating {@link IServerBase} object. + * + * This method {@link createServerBase createServerBase()} determines which protocol is used in this + * {@link DistributedClientArrayMediator} object as a **master**. If the protocol is determined, then + * {@link DistributedSystem distributed clients} who may connect to {@link DistributedClientArrayMediator this + * server} must follow the specified protocol. + * + * Overrides the {@link createServerBase createServerBase()} method to create and return one of them: + * + * - {@link ServerBase} + * - {@link WebServerBase} + * - {@link SharedWorkerServerBase} + * + * @return A new {@link IServerBase} object. + */ + protected abstract createServerBase(): protocol.IServerBase; + /** + * Add a newly connected remote client. + * + * When a {@link IClientDriver remote client} connects to this *master server of distributed processing system*, + * then this {@link DistributedClientArrayMediator} creates a child {@link Distributed distributed client} object + * through the {@link createExternalClient createExternalClient()} method. + * + * @param driver A communicator for external client. + */ + addClient(driver: protocol.IClientDriver): void; + /** + * (Deprecated) Factory method creating child object. + * + * The method {@link createChild createChild()} is deprecated. Don't use and override this. + * + * Note that, the {@link DistributedClientArrayMediator} is a server accepting {@link DistributedSystem distributed + * clients} as a master. There's no way to creating the {@link DistributedSystem distributed clients} in advance + * before opening the server. + * + * @param xml An {@link XML} object represents the child {@link DistributedSystem} object. + * @return null + */ + createChild(xml: library.XML): DistributedSystem; + /** + * Factory method creating {@link DistributedSystem} object. + * + * The method {@link createExternalClient createExternalClient()} is a factory method creating a child + * {@link DistributedSystem} object, that is called whenever a distributed client has connected, by + * {@link addClient addClient()}. + * + * Overrides this {@link createExternalClient} method and creates a type of {@link DistributedSystem} object with + * the *driver* that communicates with the distributed client. After the creation, returns the object. Then whenever + * a distributed client has connected, matched {@link DistributedSystem} object will be constructed and + * {@link insert inserted} into this {@link DistributedClientArrayMediator} object. + * + * @param driver A communicator with the distributed client. + * @return A newly created {@link DistributedSystem} object. + */ + protected abstract createExternalClient(driver: protocol.IClientDriver): DistributedSystem; + /** + * @inheritdoc + */ + open(port: number): void; + /** + * @inheritdoc + */ + close(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * A role of Distributed Processing System. + * + * The {@link DistributedProcess} is an abstract class who represents a **process**, *SOMETHING TO DISTRIBUTE* in a Distributed + * Processing System. Overrides the {@link DistributedProcess} and defines the *SOMETHING TO DISTRIBUTE*. + * + * Relationship between {@link DistributedSystem} and {@link DistributedProcess} objects are **M: N Associative**. + * Unlike {@link ExternalSystemRole}, the {@link DistributedProcess} objects are not belonged to a specific + * {@link DistributedSystem} object. The {@link DistributedProcess} objects are belonged to the + * {@link DistributedSystemArrayMediator} directly. + * + * When you need the **distributed process**, then call {@link sendData sendData()}. The {@link sendData} will find + * the most idle {@link DistributedSystem slave system} considering not only number of processes on progress, but also + * {@link DistributedSystem.getPerformance performance index} of each {@link DistributedSystem} object and + * {@link getResource resource index} of this {@link DistributedProcess} object. The {@link Invoke} message + * requesting the **distributed process** will be sent to the most idle {@link DistributedSystem slave system}. + * + * Those {@link DistributedSystem.getPerformance performance index} and {@link getResource resource index} are + * revaluated whenever the **distributed process** has completed basis on the execution time. + * + * + * + * + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedProcess extends protocol.Entity implements protocol.IProtocol { + /** + * @hidden + */ + private system_array_; + /** + * A name, represents and identifies this {@link DistributedProcess process}. + * + * This {@link name} is an identifier represents this {@link DistributedProcess process}. This {@link name} is + * used in {@link DistributedSystemArray.getProcess} and {@link DistributedSystemArray.getProcess}, as a key elements. + * Thus, this {@link name} should be unique in its parent {@link DistributedSystemArray} object. + */ + protected name: string; + /** + * @hidden + */ + private progress_list_; + /** + * @hidden + */ + private history_list_; + /** + * @hidden + */ + private resource; + /** + * @hidden + */ + private enforced_; + /** + * Constrct from parent {@link DistributedSystemArray} object. + * + * @param systemArray The parent {@link DistributedSystemArray} object. + */ + constructor(systemArray: DistributedSystemArray); + /** + * Identifier of {@link ParallelProcess} is its {@link name}. + */ + key(): string; + /** + * Get parent {@link DistributedSystemArray} object. + * + * @return The parent {@link DistributedSystemArray} object. + */ + getSystemArray(): DistributedSystemArray; + /** + * Get name, who represents and identifies this process. + */ + getName(): string; + /** + * Get resource index. + * + * Get *resource index* that indicates how much this {@link DistributedProcess role} is heavy. + * + * If this {@link DistributedProcess role} does not have any {@link Invoke} message had handled, then the + * *resource index* will be ```1.0```, which means default and average value between all + * {@link DistributedProcess} instances (that are belonged to a same {@link DistributedSystemArray} object). + * + * You can specify the *resource index* by yourself, but notice that, if the *resource index* is higher than + * other {@link DistributedProcess} objects, then this {@link DistributedProcess role} will be ordered to + * handle less processes than other {@link DistributedProcess} objects. Otherwise, the *resource index* is + * lower than others, of course, much processes will be requested. + * + * - {@link setResource setResource()} + * - {@link enforceResource enforceResource()} + * + * Unless {@link enforceResource enforceResource()} is called, This *resource index* is **revaluated** whenever + * {@link sendData sendData()} is called. + * + * @return Resource index. + */ + getResource(): number; + /** + * Set resource index. + * + * Set *resource index* that indicates how much this {@link DistributedProcess role} is heavy. This + * *resource index* can be **revaulated**. + * + * Note that, initial and average *resource index* of {@link DistributedProcess} objects are ```1.0```. If the + * *resource index* is higher than other {@link DistributedProcess} objects, then this + * {@link DistributedProcess} will be ordered to handle more processes than other {@link DistributedProcess} + * objects. Otherwise, the *resource index* is lower than others, of course, less processes will be requested. + * + * Unlike {@link enforceResource}, configuring *resource index* by this {@link setResource} allows the + * **revaluation**. This **revaluation** prevents wrong valuation from user. For example, you *mis-valuated* the + * *resource index*. The {@link DistributedProcess role} is much heavier than any other, but you estimated it + * to the lightest one. It looks like a terrible case that causes + * {@link DistributedSystemArray entire distributed processing system} to be slower, however, don't mind. The + * {@link DistributedProcess role} will the direct to the *propriate resource index* eventually with the + * **revaluation**. + * + * - The **revaluation** is caused by the {@link sendData sendData()} method. + * + * @param val New resource index, but can be revaluated. + */ + setResource(val: number): void; + /** + * Enforce resource index. + * + * Enforce *resource index* that indicates how much heavy the {@link DistributedProcess role is}. The + * *resource index* will be fixed, never be **revaluated**. + * + * Note that, initial and average *resource index* of {@link DistributedProcess} objects are ```1.0```. If the + * *resource index* is higher than other {@link DistributedProcess} objects, then this + * {@link DistributedProcess} will be ordered to handle more processes than other {@link DistributedProcess} + * objects. Otherwise, the *resource index* is lower than others, of course, less processes will be requested. + * + * The difference between {@link setResource} and this {@link enforceResource} is allowing **revaluation** or not. + * This {@link enforceResource} does not allow the **revaluation**. The *resource index* is clearly fixed and + * never be changed by the **revaluation**. But you've to keep in mind that, you can't avoid the **mis-valuation** + * with this {@link enforceResource}. + * + * For example, there's a {@link DistributedProcess role} much heavier than any other, but you + * **mis-estimated** it to the lightest. In that case, there's no way. The + * {@link DistributedSystemArray entire distributed processing system} will be slower by the **mis-valuation**. + * By the reason, using {@link enforceResource}, it's recommended only when you can clearly certain the + * *resource index*. If you can't certain the *resource index* but want to recommend, then use {@link setResource} + * instead. + * + * @param val New resource index to be fixed. + */ + enforceResource(val: number): void; + /** + * @hidden + */ + private compute_average_elapsed_time(); + /** + * @inheritdoc + */ + abstract replyData(invoke: protocol.Invoke): void; + /** + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message requesting a **distributed process**. The {@link Invoke} message will be sent + * to the most idle {@link DistributedSystem} object, which represents a slave system, and the most idle + * {@link DistributedSystem} object will be returned. + * + * When the **distributed process** has completed, then the {@link DistributedSystemArray} object will revaluate + * {@link getResource resource index} and {@link DistributedSystem.getPerformance performance index} of this + * {@link DistributedSystem} and the most idle {@link DistributedSystem} objects basis on the execution time. + * + * @param invoke An {@link Invoke} message requesting distributed process. + * @return The most idle {@link DistributedSystem} object who may send the {@link Invoke} message. + */ + sendData(invoke: protocol.Invoke): DistributedSystem; + /** + * @hidden + */ + private complete_history(history); + /** + * @inheritdoc + */ + TAG(): string; + } +} +declare namespace samchon.templates.external { + /** + * An external system driver. + * + * The {@link ExternalSystem} class represents an external system, connected and interact with this system. + * {@link ExternalSystem} takes full charge of network communication with the remote, external system have connected. + * Replied {@link Invoke} messages from the external system is shifted to and processed in, children elements of this + * class, {@link ExternalSystemRole} objects. + * + * + * + * + * + * #### Bridge & Proxy Pattern + * The {@link ExternalSystem} class can be a *bridge* for *logical proxy*. In framework within user, + * which {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Bridge Pattern* and *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalSystem extends protocol.EntityDequeCollection implements protocol.IProtocol { + /** + * The name represents external system have connected. + */ + protected name: string; + /** + * @hidden + */ + private system_array_; + /** + * @hidden + */ + private communicator_; + /** + * Construct from parent {@link ExternalSystemArray}. + * + * @param systemArray The parent {@link ExternalSystemArray} object. + */ + constructor(systemArray: ExternalSystemArray); + /** + * Constrct from parent {@link ExternalSystemArray} and communicator. + * + * @param systemArray The parent {@link ExternalSystemArray} object. + * @param communicator Communicator with the remote, external system. + */ + constructor(systemArray: ExternalSystemArray, communicator: protocol.IClientDriver); + /** + * Default Destructor. + * + * This {@link destructor destructor()} method is called when the {@link ExternalSystem} object is destructed and + * the {@link ExternalSystem} object is destructed when connection with the remote system is closed or this + * {@link ExternalSystem} object is {@link ExternalSystemArray.erase erased} from its parent + * {@link ExternalSystemArray} object. + * + * Note that, don't call this {@link destructor destructor()} method by yourself. It must be called automatically + * by those *destruction* cases. Also, if your derived {@link ExternalSystem} class has something to do on the + * *destruction*, then overrides this {@link destructor destructor()} method and defines the something to do. + * Overriding this {@link destructor destructor()}, don't forget to calling ```super.destructor();``` on tail. + * + * ```typescript + * class SomeSystem extends templates.external.ExternalSystem + * { + * protected destructor(): void + * { + * // DO SOMETHING + * this.do_something(); + * + * // CALL SUPER.DESTRUCTOR() ON TAIL. DON'T FORGET THIS + * super.destructor(); + * } + * } + * ``` + */ + protected destructor(): void; + /** + * @hidden + */ + private handle_close(); + /** + * Get parent {@link ExternalSystemArray} object. + */ + getSystemArray(): ExternalSystemArray; + /** + * Identifier of {@link ExternalSystem} is its {@link name}. + * + * @return name. + */ + key(): string; + /** + * Get {@link name}. + */ + getName(): string; + /** + * @hidden + */ + /** + * @hidden + */ + protected communicator: protocol.ICommunicator; + /** + * Close connection. + */ + close(): void; + /** + * Send {@link Invoke} message to external system. + * + * @param invoke An {@link Invoke} message to send. + */ + sendData(invoke: protocol.Invoke): void; + /** + * Handle an {@Invoke} message has received. + * + * @param invoke An {@link Invoke} message have received. + */ + replyData(invoke: protocol.Invoke): void; + /** + * Tag name of the {@link ExternalSystem} in {@link XML}. + * + * @return *system*. + */ + TAG(): string; + /** + * Tag name of {@link ExternalSystemRole children elements} belonged to the {@link ExternalSystem} in {@link XML}. + * + * @return *role*. + */ + CHILD_TAG(): string; + } +} +declare namespace samchon.templates.parallel { + /** + * A driver for a parallel slave system. + * + * The {@link ParallelSystem} is an abstract class represents a **slave** system in *Parallel Processing System*, + * connected with this **master** system. This {@link ParallelSystem} takes full charge of network communication with + * the remote, parallel **slave** system has connected. + * + * When a *parallel process* is requested (by {@link ParallelSystemArray.sendSegementData} or + * {@link ParallelSystemArray.sendPieceData}), the number of pieces to be allocated to a {@link ParallelSystem} is + * turn on its {@link getPerformance performance index}. Higher {@link getPerformance performance index}, then + * more pieces are requested. The {@link getPerformance performance index} is revaluated whenever a *parallel process* + * has completed, basic on the execution time and number of pieces. You can sugguest or enforce the + * {@link getPerformance performance index} with {@link setPerformance} or {@link enforcePerformance}. + * + * + * + * + * + * #### Bridge & Proxy Pattern + * This class {@link ParallelSystem} is derived from the {@link ExternalSystem} class. Thus, you can take advantage + * of the *Bridge & Proxy Pattern* in this {@link ParallelSystem} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Bridge & Proxy Pattern*: + * + * The {@link ExternalSystem} class can be a *bridge* for *logical proxy*. In framework within user, + * which {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Bridge Pattern* and *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + abstract class ParallelSystem extends external.ExternalSystem { + /** + * @hidden + */ + private progress_list_; + /** + * @hidden + */ + private history_list_; + /** + * @hidden + */ + private exclude_; + /** + * @hidden + */ + private performance; + /** + * @hidden + */ + private enforced_; + /** + * Construct from parent {@link ParallelSystemArray}. + * + * @param systemArray The parent {@link ParallelSystemArray} object. + */ + constructor(systemArray: ParallelSystemArray); + /** + * Construct from parent {@link ParallelSystemArray} and communicator. + * + * @param systemArray The parent {@link ParallelSystemArray} object. + * @param communicator A communicator communicates with remote, the external system. + */ + constructor(systemArray: ParallelSystemArray, communicator: protocol.IClientDriver); + /** + * Default Destructor. + * + * This {@link destructor destructor()} method is called when the {@link ParallelSystem} object is destructed and + * the {@link ParallelSystem} object is destructed when connection with the remote system is closed or this + * {@link ParallelSystem} object is {@link ParallelSystemArray.erase erased} from its parent + * {@link ParallelSystemArray} object. + * + * You may think if there're some *parallel processes* have requested but not completed yet, then it would be a + * critical problem because the *parallel processes* will not complete forever. Do not worry. The critical problem + * does not happen. After the destruction, the remained *parallel processes* will be shifted to and proceeded in + * other {@link ParallelSystem} objects. + * + * Note that, don't call this {@link destructor destructor()} method by yourself. It must be called automatically + * by those *destruction* cases. Also, if your derived {@link ParallelSystem} class has something to do on the + * *destruction*, then overrides this {@link destructor destructor()} method and defines the something to do. + * Overriding this {@link destructor destructor()}, don't forget to calling ```super.destructor();``` on tail. + * + * ```typescript + * class SomeSystem extends protocol.external.ExternalSystem + * { + * protected destructor(): void + * { + * // DO SOMETHING + * this.do_something(); + * + * // CALL SUPER.DESTRUCTOR() ON TAIL. DON'T FORGET THIS + * super.destructor(); + * } + * } + * ``` + */ + protected destructor(): void; + /** + * Get manager of this object. + * + * @return The parent {@link ParallelSystemArray} object. + */ + getSystemArray(): ParallelSystemArray; + /** + * Get performance index. + * + * Get *performance index* that indicates how much fast the remote system is. + * + * If this {@link ParallelSystem parallel system} does not have any {@link Invoke} message had handled, then the + * *performance index* will be ```1.0```, which means default and average value between all {@link ParallelSystem} + * instances (that are belonged to a same {@link ParallelSystemArray} object). + * + * You can specify this *performance index* by yourself but notice that, if the *performance index* is higher + * than other {@link ParallelSystem} objects, then this {@link ParallelSystem parallel system} will be ordered to + * handle more processes than other {@link ParallelSystem} objects. Otherwise, the *performance index* is lower + * than others, of course, less processes will be delivered. + * + * - {@link setPerformance setPerformance()} + * - {@link enforcePerformance enforcePerformance()} + * + * Unless {@link enforcePerformance enforcePerformance()} is called, This *performance index* is **revaluated** + * whenever user calls one of them below. + * + * - {@link ParallelSystemArray.sendSegmentData ParallelSystemArray.sendSegmentData()} + * - {@link ParallelSystemArray.sendPieceData ParallelSystemArray.sendPieceData()} + * - {@link DistributedProcess.sendData DistributedProcess.sendData()}. + * + * @return Performance index. + */ + getPerformance(): number; + /** + * Set performance index. + * + * Set *performance index* that indicates how much fast the remote system is. This *performance index* can be + * **revaulated**. + * + * Note that, initial and average *performance index* of {@link ParallelSystem} objects are ```1.0```. If the + * *performance index* is higher than other {@link ParallelSystem} objects, then this {@link ParallelSystem} will + * be ordered to handle more processes than other {@link ParallelSystem} objects. Otherwise, the + * *performance index* is lower than others, of course, less processes will be delivered. + * + * Unlike {@link enforcePerformance}, configuring *performance index* by this {@link setPerformance} allows + * **revaluation**. This **revaluation** prevents wrong valuation from user. For example, you *mis-valuated* the + * *performance index*. The remote system is much faster than any other, but you estimated it to the slowest one. + * It looks like a terrible case that causes {@link ParallelSystemArray entire parallel systems} to be slower, + * however, don't mind. The system will direct to the *propriate performance index* eventually with the + * **revaluation** by following methods. + * + * - {@link ParallelSystemArray.sendSegmentData ParallelSystemArray.sendSegmentData()} + * - {@link ParallelSystemArray.sendPieceData ParallelSystemArray.sendPieceData()} + * - {@link DistributedProcess.sendData DistributedProcess.sendData()}. + * + * @param val New performance index, but can be revaluated. + */ + setPerformance(val: number): void; + /** + * Enforce performance index. + * + * Enforce *performance index* that indicates how much fast the remote system is. The *performance index* will be + * fixed, never be **revaluated**. + * + * Note that, initial and average *performance index* of {@link ParallelSystem} objects are ```1.0```. If the + * *performance index* is higher than other {@link ParallelSystem} objects, then this {@link ParallelSystem} will + * be ordered to handle more processes than other {@link ParallelSystem} objects. Otherwise, the + * *performance index* is lower than others, of course, less processes will be delivered. + * + * The difference between {@link setPerformance} and this {@link enforcePerformance} is allowing **revaluation** + * or not. This {@link enforcePerformance} does not allow the **revaluation**. The *performance index* is clearly + * fixed and never be changed by the **revaluation**. But you've to keep in mind that, you can't avoid the + * **mis-valuation** with this {@link enforcePerformance}. + * + * For example, there's a remote system much faster than any other, but you **mis-estimated** it to the slowest. + * In that case, there's no way. The {@link ParallelSystemArray entire parallel systems} will be slower by the + * **mis-valuation**. By the reason, using {@link enforcePerformance}, it's recommended only when you can clearly + * certain the *performance index*. If you can't certain the *performance index* but want to recommend, then use + * {@link setPerformance} instead. + * + * @param val New performance index to be fixed. + */ + enforcePerformance(val: number): void; + /** + * @hidden + */ + private send_piece_data(invoke, first, last); + /** + * @hidden + */ + private _replyData(invoke); + /** + * @hidden + */ + protected _Report_history(xml: library.XML): void; + /** + * @hidden + */ + protected _Send_back_history(invoke: protocol.Invoke, history: protocol.InvokeHistory): void; + } +} +declare namespace samchon.templates.distributed { + /** + * A driver for a distributed slave system. + * + * The {@link DistributedSystem} is an abstract class represents a **slave** system in *Distributed Processing System*, + * connected with this **master** system. This {@link DistributedSystem} takes full charge of network communication + * with the remote, distributed **slave** system has connected. + * + * This {@link DistributedSystem} has a {@link getPerformance performance index} that indicates how much the **slave** + * system is fast. The {@link getPerformance performance index} is referenced and revaluated whenever those methods + * are called: + * + * - Requesting a *parallel process* + * - {@link DistributedSystemArray.sendSegmentData} + * - {@link DistributedSystemArray.sendPieceData} + * - Requesting a *distributed process*: {@link DistributedProcess.sendData} + * + * Note that, this {@link DistributedSystem} class derived from the {@link ExternalSystem} class. Thus, this + * {@link DistributedSystem} can also have children {@link ExternalSystemRole} objects exclusively. However, the + * children {@link ExternalSystemRole roles} objects are different with the {@link DistributedProcess}. The + * domestic {@link ExternalSystemRole roles} are belonged to only a specific {@link DistributedSystem} object. + * Otherwise, the {@link DistributedProcess} objects are belonged to a {@link DistributedSystemArray} object. + * Furthermore, the relationship between this {@link DistributedSystem} and {@link DistributedProcess} classes are + * **M: N Associative**. + * + * Articles | {@link DistributedProcess} | {@link ExternalSystemRole} + * -------------|--------------------------------|---------------------------- + * Belonged to | {@link DistributedSystemArray} | {@link DistributedSystem} + * Relationship | M: N Associative | 1: N Composite + * Ownership | References | Exclusive possession + * + * + * + * + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedSystem extends parallel.ParallelSystem { + /** + * Construct from parent {@link DistributedSystemArray}. + * + * @param systemArray The parent {@link DistributedSystemArray} object. + */ + constructor(systemArray: DistributedSystemArray); + /** + * Constrct from parent {@link DistributedSystemArray} and communicator. + * + * @param systemArray The parent {@link DistributedSystemArray} object. + * @param communicator A communicator communicates with remote, the external system. + */ + constructor(systemArray: DistributedSystemArray, communicator: protocol.IClientDriver); + /** + * Factory method creating a {@link ExternalSystemRole child} object. + * + * In {@link distributed} module, the process class {@link DistributedProcess} is not belonged to a specific + * {@link DistributedSystem} object. It only belongs to a {@link DistributedSystemArray} object and has a + * **M: N Associative Relationship** between this {@link DistributedSystem} class. + * + * By that reason, it's the normal case that the {@link DistributedSystem} object does not have any children + * {@link ExternalSystemRole} object. Thus, default {@link createChild} returns ```null```. + * + * However, if you want a {@link DistributedSystem} to have its own domestic {@link ExternalSystemRole} objects + * without reference to the {@link DistributedProcess} objects, it is possible. Creates and returns the + * domestic {@link ExternalSystemRole} object. + * + * @param xml {@link XML} represents the {@link ExternalSystemRole child} object. + * @return A newly created {@link ExternalSystemRole} object or ```null```. + */ + createChild(xml: library.XML): external.ExternalSystemRole; + /** + * Get parent {@link DistributedSystemArray} object. + * + * @return The parent {@link DistributedSystemArray} object. + */ + getSystemArray(): DistributedSystemArray; + /** + * @hidden + */ + private compute_average_elapsed_time(); + /** + * @inheritdoc + */ + replyData(invoke: protocol.Invoke): void; + /** + * @hidden + */ + protected _Report_history(xml: library.XML): void; + /** + * @hidden + */ + protected _Send_back_history(invoke: protocol.Invoke, history: protocol.InvokeHistory): void; + } +} +declare namespace samchon.templates.distributed { + /** + * An interface for a distributed slave server driver. + * + * The easiest way to defining a driver for distributed **slave** server is extending {@link DistributedServer} class. + * However, if you've to interact with a prallel **slave** system who can be both server and client, them make a class + * (let's name it **BaseSystem**) extending the {@link DistributedServer} class. At next, make a new class (now, I name + * it **BaseServer**) extending the **BaseSystem** and implements this interface {@link IParallelServer}. Define the + * **BaseServer** following those codes on below: + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + interface IDistributedServer extends DistributedSystem { + /** + * Connect to external server. + */ + connect(): void; + } + /** + * A driver for distributed slave server. + * + * The {@link DistributedServer} is an abstract class, derived from the {@link DistributedSystem} class, connecting to + * remote, distributed **slave** server. Extends this {@link DistributedServer} class and overrides the + * {@link createServerConnector createServerConnector()} method following which protocol the **slave** server uses. + * + * #### [Inheritdoc] {@link DistributedSystem} + * The {@link DistributedSystem} is an abstract class represents a **slave** system in *Distributed Processing System*, + * connected with this **master** system. This {@link DistributedSystem} takes full charge of network communication + * with the remote, distributed **slave** system has connected. + * + * This {@link DistributedSystem} has a {@link getPerformance performance index} that indicates how much the **slave** + * system is fast. The {@link getPerformance performance index} is referenced and revaluated whenever those methods + * are called: + * + * - Requesting a *parallel process* + * - {@link DistributedSystemArray.sendSegmentData} + * - {@link DistributedSystemArray.sendPieceData} + * - Requesting a *distributed process*: {@link DistributedProcess.sendData} + * + * Note that, this {@link DistributedSystem} class derived from the {@link ExternalSystem} class. Thus, this + * {@link DistributedSystem} can also have children {@link ExternalSystemRole} objects exclusively. However, the + * children {@link ExternalSystemRole roles} objects are different with the {@link DistributedProcess}. The + * domestic {@link ExternalSystemRole roles} are belonged to only a specific {@link DistributedSystem} object. + * Otherwise, the {@link DistributedProcess} objects are belonged to a {@link DistributedSystemArray} object. + * Furthermore, the relationship between this {@link DistributedSystem} and {@link DistributedProcess} classes are + * **M: N Associative**. + * + * Articles | {@link DistributedProcess} | {@link ExternalSystemRole} + * -------------|--------------------------------|---------------------------- + * Belonged to | {@link DistributedSystemArray} | {@link DistributedSystem} + * Relationship | M: N Associative | 1: N Composite + * Ownership | References | Exclusive possession + * + * + * + * + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedServer extends DistributedSystem implements external.IExternalServer { + /** + * IP address of target external system to connect. + */ + protected ip: string; + /** + * Port number of target external system to connect. + */ + protected port: number; + /** + * Construct from parent {@link DistributedSystemArray}. + * + * @param systemArray The parent {@link DistributedSystemArray} object. + */ + constructor(systemArray: DistributedSystemArray); + /** + * Factory method creating {@link IServerConnector} object. + * + * The {@link createServerConnector createServerConnector()} is an abstract method creating + * {@link IServerConnector} object. Overrides and returns one of them, considering which protocol the slave server + * follows: + * + * - {@link ServerConnector} + * - {@link WebServerConnector} + * - {@link SharedWorkerServerConnector} + * + * @return A newly created {@link IServerConnector} object. + */ + protected abstract createServerConnector(): protocol.IServerConnector; + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * Master of Distributed Processing System, a client connecting to slave servers. + * + * The {@link DistributedServerArray} is an abstract class, derived from the {@link DistributedSystemArray} class, + * connecting to {@link IDistributedServer distributed servers}. + * + * Extends this {@link DistributedServerArray} and overrides {@link createChild createChild()} method creating child + * {@link IDistributedServer} object. After the extending and overriding, construct children {@link IDistributedServer} + * objects and call the {@link connect connect()} method. + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedServerArray extends DistributedSystemArray implements external.IExternalServerArray { + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * Mediator of Distributed Processing System, a client connecting to slave servers. + * + * The {@link DistributedServerArrayMediator} is an abstract class, derived from {@link DistributedSystemArrayMediator} + * class, connecting to {@link IDistributedServer distributed servers}. + * + * Extends this {@link DistributedServerArrayMediator} and overrides {@link createChild createChild()} method creating + * child {@link IDistributedServer} object. After the extending and overriding, construct children + * {@link IDistributedServer} objects and call the {@link connect connect()} method. + * + * #### [Inherited] {@link DistributedSystemArrayMediator} + * The {@link DistributedSystemArrayMediator} class be a master for its slave systems, and be a slave to its master + * system at the same time. This {@link DistributedSystemArrayMediator} be a master system, containing and managing + * {@link DistributedSystem} objects, which represent distributed slave systems, by extending + * {@link DistributedSystemArray} class. Also, be a slave system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a slave, you can specify this {@link DistributedSystemArrayMediator} to be a client slave connecting to master + * server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedServerArrayMediator extends DistributedSystemArrayMediator implements external.IExternalServerArray { + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * Master of Distributed Processing System, be a server and client at the same time. + * + * The {@link DistributedServerClientArray} is an abstract class, derived from the {@link DistributedSystemArray} + * class, opening a server accepting {@link Distributed distributed clients} and being a client connecting to + * {@link IDistributedServer distributed servers} at the same time. + * + * Extends this {@link DistributedServerClientArray} and overrides below methods. After the overridings, open server + * with {@link open open()} method and connect to {@link IDistributedServer distributed servers} through the + * {@link connect connect()} method. + * + * - {@link createServerBase createServerBase()} + * - {@link createExternalClient createExternalClient()} + * - {@link createExternalServer createExternalServer()} + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedServerClientArray extends DistributedClientArray implements external.IExternalServerClientArray { + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method of a child Entity. + * + * This method is migrated to {@link createExternalServer}. Override the {@link createExternalServer} method. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A new child Entity via {@link createExternalServer createExternalServer()}. + */ + createChild(xml: library.XML): DistributedSystem; + /** + * Factory method creating an {@link IDistributedServer} object. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A newly created {@link IDistributedServer} object. + */ + protected abstract createExternalServer(xml: library.XML): IDistributedServer; + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.distributed { + /** + * Mediator of Distributed Processing System, be a server and client at the same time as a **master**. + * + * The {@link DistributedServerClientArrayMediator} is an abstract class, derived from the + * {@link DistributedSystemArrayMediator} class, opening a server accepting {@link DistributedSystem distributed + * clients} and being a client connecting to {@link IDistributedServer distributed servers} at the same time. + * + * Extends this {@link DistributedServerClientArrayMediator} and overrides below methods. After the overridings, open + * server with {@link open open()} method and connect to {@link IDistributedServer distributed servers} through the + * {@link connect connect()} method. + * + * - {@link createServerBase createServerBase()} + * - {@link createExternalClient createExternalClient()} + * - {@link createExternalServer createExternalServer()} + * + * #### [Inherited] {@link DistributedSystemArrayMediator} + * The {@link DistributedSystemArrayMediator} class be a master for its slave systems, and be a slave to its master + * system at the same time. This {@link DistributedSystemArrayMediator} be a master system, containing and managing + * {@link DistributedSystem} objects, which represent distributed slave systems, by extending + * {@link DistributedSystemArray} class. Also, be a slave system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a slave, you can specify this {@link DistributedSystemArrayMediator} to be a client slave connecting to master + * server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link DistributedSystemArray} + * The {@link DistributedSystemArray} is an abstract class containing and managing remote distributed **slave** system + * drivers, {@link DistributedSystem} objects. Within framework of network, {@link DistributedSystemArray} represents + * your system, a **Master** of *Distributed Processing System* that requesting *distributed process* to **slave** + * systems and the children {@link DistributedSystem} objects represent the remote **slave** systems, who is being + * requested the *distributed processes*. + * + * The {@link DistributedSystemArray} contains {@link DistributedProcess} objects directly. You can request a + * **distributed process** through the {@link DistributedProcess} object. You can access the + * {@link DistributedProcess} object(s) with those methods: + * + * - {@link hasRole} + * - {@link getRole} + * - {@link insertRole} + * - {@link eraseRole} + * - {@link getRoleMap} + * + * When you need the **distributed process**, call the {@link DistributedProcess.sendData} method. Then the + * {@link DistributedProcess} will find the most idle {@link DistributedSystem} object who represents a distributed + * **slave **system. The {@link Invoke} message will be sent to the most idle {@link DistributedSystem} object. When + * the **distributed process** has completed, then {@link DistributedSystem.getPerformance performance index} and + * {@link DistributedProcess.getResource resource index} of related objects will be revaluated. + * + * + * + * + * + * #### Parallel Process + * This {@link DistributedSystemArray} class is derived from the {@link ParallelSystemArray} class, so you can request + * a **parallel process**, too. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices will + * be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * #### Proxy Pattern + * This class {@link DistributedSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link DistributedSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class DistributedServerClientArrayMediator extends DistributedClientArrayMediator implements external.IExternalServerClientArray { + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method of a child Entity. + * + * This method is migrated to {@link createExternalServer}. Override the {@link createExternalServer} method. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A new child Entity via {@link createExternalServer createExternalServer()}. + */ + createChild(xml: library.XML): DistributedSystem; + /** + * Factory method creating an {@link IDistributedServer} object. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A newly created {@link IDistributedServer} object. + */ + protected abstract createExternalServer(xml: library.XML): IDistributedServer; + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.external { + /** + * An interface for an {@link ExternalSystemArray} accepts {@link ExternalSystem external clients} as a + * {@link IServer server}. + * + * The easiest way to defining an {@link ExternalSystemArray} who opens server and accepts + * {@link ExternalSystem external clients} is to extending one of below, who are derived from this interface + * {@link IExternalClientArray}. However, if you can't specify an {@link ExternalSystemArray} to be whether server or + * client, then make a class (let's name it as **BaseSystemArray**) extending {@link ExternalSystemArray} and make + * a new class (now, I name it **BaseClientArray**) extending **BaseSystemArray** and implementing this + * interface {@link IExternalClientArray}. Define the **BaseClientArray** following those codes on below: + * + * + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + interface IExternalClientArray extends ExternalSystemArray, protocol.IServer { + } + /** + * An array and manager of {@link ExternalSystem external clients} as a server. + * + * The {@link ExternalClientArray} is an abstract class, derived from the {@link ExternalSystemArray} class, opening + * a server accepting {@link ExternalSystem external clients}. + * + * Extends this {@link ExternalClientArray}, overrides {@link createServerBase createServerBase()} to determine which + * protocol to follow and {@link createExternalClient createExternalClient()} creating child {@link ExternalSystem} + * object. After the extending and overridings, open this server using the {@link open open()} method. + * + * #### [Inherited] {@link ExternalSystemArray} + * The {@link ExternalSystemArray} is an abstract class containing and managing external system drivers, + * {@link ExternalSystem} objects. Within framewokr of network, {@link ExternalSystemArray} represents your system + * and children {@link ExternalSystem} objects represent remote, external systems connected with your system. + * With this {@link ExternalSystemArray}, you can manage multiple external systems as a group. + * + * + * + * + * + * #### Proxy Pattern + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalClientArray extends ExternalSystemArray implements IExternalClientArray { + /** + * @hidden + */ + private server_base_; + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method creating {@link IServerBase} object. + * + * This method {@link createServerBase createServerBase()} determines which templates is used in this server, + * {@link ExternalClientArray}. If the templates is determined, then {@link ExternalSystem external clients} who + * may connect to {@link ExternalClientArray this server} must follow the specified templates. + * + * Creates and returns one of them: + *
          + *
        • {@link ServerBase}
          • + *
        • {@link WebServerBase}
          • + *
        • {@link SharedWorkerServerBase}
          • + *
        + * + * @return A new {@link IServerBase} object. + */ + protected abstract createServerBase(): protocol.IServerBase; + /** + * Add a newly connected remote client. + * + * When a {@link IClientDriver remote client} connects to this *server* {@link ExternalClientArray} object, + * then this {@link ExternalClientArray} creates a child {@link ExternalSystem external client} object through + * the {@link createExternalClient createExternalClient()} method and {@link insert inserts} it. + * + * @param driver A communicator for external client. + */ + addClient(driver: protocol.IClientDriver): void; + /** + * (Deprecated) Factory method creating child object. + * + * The method {@link createChild createChild()} is deprecated. Don't use and override this. + * + * Note that, the {@link ExternalClientArray} is a server accepting {@link ExternalSystem external clients}. + * There's no way to creating the {@link ExternalSystem external clients} in advance before opening the server. + * + * @param xml An {@link XML} object represents the child {@link ExternalSystem} object. + * @return null + */ + createChild(xml: library.XML): ExternalSystem; + /** + * Factory method creating a child {@link ExternalSystem} object. + * + * @param driver A communicator with connected client. + * @return A newly created {@link ExternalSystem} object. + */ + protected abstract createExternalClient(driver: protocol.IClientDriver): ExternalSystem; + /** + * @inheritdoc + */ + open(port: number): void; + /** + * @inheritdoc + */ + close(): void; + } +} +declare namespace samchon.templates.external { + /** + * An interface for an external server driver. + * + * The easiest way to defining an external server driver is to extending one of below, who are derived from this + * interface {@link IExternalServer}. However, if you've to interact with an external system who can be both server + * and client, then make a class (let's name it as **BaseSystem**) extending {@link ExternalSystem} and make a + * new class (now, I name it **BaseServer**) extending **BaseSystem** and implementing this interface + * {@link IExternalServer}. Define the **BaseServer** following those codes on below: + * + * + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + interface IExternalServer extends ExternalSystem { + /** + * Connect to external server. + */ + connect(): void; + } + /** + * An external server driver. + * + * The {@link ExternalServer} is an abstract class, derived from the {@link ExternalSystem} class, connecting to + * remote, external server. Extends this {@link ExternalServer} class and overrides the + * {@link createServerConnector createServerConnector()} method following which protocol the external server uses. + * + * #### [Inherited] {@link ExternalSystem} + * The {@link ExternalSystem} class represents an external system, connected and interact with this system. + * {@link ExternalSystem} takes full charge of network communication with the remote, external system have connected. + * Replied {@link Invoke} messages from the external system is shifted to and processed in, children elements of this + * class, {@link ExternalSystemRole} objects. + * + * + * + * + * + * #### Bridge & Proxy Pattern + * The {@link ExternalSystem} class can be a *bridge* for *logical proxy*. In framework within user, + * which {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Bridge Pattern* and *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalServer extends ExternalSystem implements IExternalServer { + /** + * IP address of target external system to connect. + */ + protected ip: string; + /** + * Port number of target external system to connect. + */ + protected port: number; + /** + * Construct from parent {@link ExternalSystemArray}. + * + * @param systemArray The parent {@link ExternalSystemArray} object. + */ + constructor(systemArray: ExternalSystemArray); + /** + * Factory method creating {@link IServerConnector} object. + * + * The {@link createServerConnector createServerConnector()} is an abstract method creating + * {@link IServerConnector} object. Overrides and returns one of them, considering which templates the external + * system follows: + * + * - {@link ServerConnector} + * - {@link WebServerConnector} + * - {@link SharedWorkerServerConnector} + * + * @return A newly created {@link IServerConnector} object. + */ + protected abstract createServerConnector(): protocol.IServerConnector; + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.external { + /** + * An interface for an {@link ExternalSystemArray} connects to {@link IExternalServer external servers} as a + * **client**. + * + * The easiest way to defining an {@link ExternalSystemArray} who connects to + * {@link IExternalServer external servers} is to extending one of below, who are derived from this interface + * {@link IExternalServerArray}. However, if you can't specify an {@link ExternalSystemArray} to be whether server or + * client, then make a class (let's name it as **BaseSystemArray**) extending {@link ExternalSystemArray} and make + * a new class (now, I name it **BaseServerArray**) extending **BaseSystemArray** and implementing this + * interface {@link IExternalServerArray}. Define the **BaseServerArray** following those codes on below: + * + * + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + interface IExternalServerArray extends ExternalSystemArray { + /** + * Connect to {@link IExternalServer external servers}. + * + * This method calls children elements' method {@link IExternalServer.connect} gradually. + */ + connect(): void; + } + /** + * An array and manager of {@link IExternalServer external servers}. + * + * The {@link ExternalServerArray} is an abstract class, derived from the {@link ExternalSystemArray} class, + * connecting to {@link IExternalServer external servers}. + * + * Extends this {@link ExternalServerArray} and overrides {@link createChild createChild()} method creating child + * {@link IExternalServer} object. After the extending and overriding, construct children {@link IExternalServer} + * objects and call the {@link connect connect()} method. + * + * #### [Inherited] {@link ExternalSystemArray} + * The {@link ExternalSystemArray} is an abstract class containing and managing external system drivers, + * {@link ExternalSystem} objects. Within framewokr of network, {@link ExternalSystemArray} represents your system + * and children {@link ExternalSystem} objects represent remote, external systems connected with your system. + * With this {@link ExternalSystemArray}, you can manage multiple external systems as a group. + * + * + * + * + * + * #### Proxy Pattern + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalServerArray extends ExternalSystemArray { + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.external { + /** + * An interface for an {@link ExternalSystemArray} accepts {@link ExternalSystem external clients} as a + * {@link IServer server} and connects to {@link IExternalServer} as **client**, at the same time. + * + * The easiest way to defining an {@link IExternalServerClientArray} who opens server, accepts + * {@link ExternalSystem external clients} and connects to {@link IExternalServer external servers} is to extending + * one of below, who are derived from this interface {@link IExternalServerClientArray}. However, if you can't + * specify an {@link ExternalSystemArray} to be whether server or client or even can both them, then make a class + * (let's name it as **BaseSystemArray**) extending {@link ExternalSystemArray} and make a new class (now, I name + * it **BaseServerClientArray**) extending **BaseSystemArray** and implementing this interface + * {@link IExternalServerClientArray}. Define the **BaseServerClientArray** following those codes on below: + * + * + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + interface IExternalServerClientArray extends IExternalServerArray, IExternalClientArray { + } + /** + * An array and manager of {@link IExternalServer external servers} and {@link ExternalSystem external clients}. + * + * The {@link ExternalServerClientArray} is an abstract class, derived from the {@link ExternalSystemArray} class, + * opening a server accepting {@link ExternalSystem external clients} and being a client connecting to + * {@link IExternalServer external servers} at the same time. + * + * Extends this {@link ExternalServerClientArray} and overrides below methods. After the overridings, open server + * with {@link open open()} method and connect to {@link IExternalServer external servers} through the + * {@link connect connect()} method. + * + * - {@link createServerBase createServerBase()} + * - {@link createExternalClient createExternalClient()} + * - {@link createExternalServer createExternalServer()} + * + * #### [Inherited] {@link ExternalSystemArray} + * The {@link ExternalSystemArray} is an abstract class containing and managing external system drivers, + * {@link ExternalSystem} objects. Within framewokr of network, {@link ExternalSystemArray} represents your system + * and children {@link ExternalSystem} objects represent remote, external systems connected with your system. + * With this {@link ExternalSystemArray}, you can manage multiple external systems as a group. + * + * + * + * + * + * #### Proxy Pattern + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalServerClientArray extends ExternalClientArray implements IExternalServerClientArray { + /** + * Default Constructor. + */ + constructor(); + /** + * Factory method of a child Entity. + * + * This method is migrated to {@link createExternalServer}. Override the {@link createExternalServer} method. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A new child Entity via {@link createExternalServer createExternalServer()}. + */ + createChild(xml: library.XML): ExternalSystem; + /** + * Factory method creating an {@link IExternalServer} object. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A newly created {@link IExternalServer} object. + */ + protected abstract createExternalServer(xml: library.XML): IExternalServer; + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.external { + /** + * A role of an external system. + * + * The {@link ExternalSystemRole} class represents a role, *WHAT TO DO*. Extends the {@link ExternalSystemRole} class + * and overrides {@link replyData replyData()} to define the *WHAT TO DO*. And assign this {@link ExternalSystemRole} + * object to related {@link ExternalSystem} object. + * + * + * + * + * + * #### Proxy Pattern + * The {@link ExternalSystemRole} class can be an *logical proxy*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem} object, via {@link ExternalSystemArray.getRole ExternalSystemArray.getRole()}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - External System](https://github.com/samchon/framework/wiki/TypeScript-Templates-External_System) + * @author Jeongho Nam + */ + abstract class ExternalSystemRole extends protocol.Entity implements protocol.IProtocol { + /** + * @hidden */ private system; /** - *

        A name, represents and identifies this {@link ExternalSystemRole role}.

        + * A name, represents and identifies this {@link ExternalSystemRole role}. * - *

        This {@link name} is an identifier represents this {@link ExternalSystemRole role}. This {@link name} is + * This {@link name} is an identifier represents this {@link ExternalSystemRole role}. This {@link name} is * used in {@link ExternalSystemArray.getRole} and {@link ExternalSystem.get}, as a key elements. Thus, this * {@link name} should be unique in an {@link ExternalSystemArray}. */ @@ -5046,7 +8194,16 @@ declare namespace samchon.protocol.external { */ key(): string; /** - * Get external system, this role is belonged to. + * Get grandparent {@link ExternalSystemArray}. + * + * Get the grandparent {@link ExternalSystemArray} object through this parent {@link ExternalSystem}, + * {@link ExternalSystem.getSystemArray ExternalSystem.getSystemArray()}. + * + * @return The grandparent {@link ExternalSystemArray} object. + */ + getSystemArray(): ExternalSystemArray; + /** + * Get parent {@link ExternalSystemRole} object. */ getSystem(): ExternalSystem; /** @@ -5054,76 +8211,608 @@ declare namespace samchon.protocol.external { */ getName(): string; /** - * Send an {@link Invoke} message to the external system via {@link system}. + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message to remote system through the parent {@link ExternalSystem} object. * * @param invoke An {@link Invoke} message to send to the external system. */ - sendData(invoke: Invoke): void; + sendData(invoke: protocol.Invoke): void; /** - *

        Handle replied {@link Invoke message} from the {@link system external system} belonged to.

        + * Handle replied {@link Invoke} message. * - *

        This {@link replyData replyData()} will call a member method named following {@link Invoke.listener}. - * in the invoke.

        + * {@link ExternalSystemRole.replyData ExternalSystemRole.replyData()} is an abstract method handling a replied + * {@link Invoke message} gotten from remote system via parent {@link ExternalSystem} object. Overrides this + * method and defines the *WHAT TO DO* with the {@link Invoke message}. * - * @param invoke An {@link Invoke} message received from the {@link system external system}. + * @param invoke An {@link Invoke} message received from the {@link ExternalSystem external system}. */ - replyData(invoke: Invoke): void; + abstract replyData(invoke: protocol.Invoke): void; /** * Tag name of the {@link ExternalSytemRole} in {@link XML}. * - * @return role. + * @return *role*. */ TAG(): string; } } -declare namespace samchon.protocol.distributed { - abstract class DistributedSystemRole extends external.ExternalSystemRole { - private system_array_; - private progress_list_; - private history_list_; - protected performance: number; - constructor(systemArray: DistributedSystemArray); - getSystemArray(): DistributedSystemArray; - getPerformance(): number; +declare namespace samchon.templates.slave { + abstract class SlaveSystem implements protocol.IProtocol { + /** + * @hidden + */ + protected communicator_: protocol.ICommunicator; + /** + * Default Constructor. + */ + constructor(); sendData(invoke: protocol.Invoke): void; - _Report_history(history: DSInvokeHistory): void; + /** + * @hidden + */ + protected _replyData(invoke: protocol.Invoke): void; + replyData(invoke: protocol.Invoke): void; } } -/** - * [[include: https://raw.githubusercontent.com/samchon/framework/master/handbook/TypeScript-Protocol-External_System.md]] - */ -declare namespace samchon.protocol.external { +declare namespace samchon.templates.parallel { /** - *

        An array and manager of {@link ExternalSystem external systems}.

        + * A mediator, the master driver. * - *

        {@link ExternalSystemArray} is an abstract class contains and manages external system drivers, - * {@link ExternalSystem} objects. You can specify this {@link ExternalSystemArray} to be a server accepting - * {@link ExternalSystem external clients} or a client connecting to {@link IExternalServer external servers}. Even - * both of them is also possible.

        + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. * - *
          - *
        • A server accepting external clients: {@link IExternalClientArray}
          • - *
        • A client connecting to external servers: {@link IExternalServerArray}
          • - *
        • - * Accepts external clients & Connects to external servers at the same time: - * {@link IExternalServerClientArray} - *
          • - *
        + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: * - *

        - * - *

        + * * - *

        Proxy Pattern

        - *

        The {@link ExternalSystemArray} class can use Proxy Pattern. In framework within user, which + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + abstract class MediatorSystem extends slave.SlaveSystem { + /** + * @hidden + */ + private system_array_; + /** + * @hidden + */ + private progress_list_; + /** + * Construct from parent {@link ParallelSystemArrayMediator} object. + * + * @param systemArray The parent {@link ParallelSystemArrayMediator} object. + */ + constructor(systemArray: ParallelSystemArrayMediator); + /** + * Construct from parent {@link DistributedSystemArrayMediator} object. + * + * @param systemArray The parent {@link DistributedSystemArrayMediator} object. + */ + constructor(systemArray: distributed.DistributedSystemArrayMediator); + /** + * Start interaction. + * + * The {@link start start()} is an abstract method starting interaction with the **master** system. If the + * **master** is a server, then connects to the **master**. Otherwise, the **master** is client, then this + * {@link MediatorSystem} object wil open a server accepting the **master**. + */ + abstract start(): void; + /** + * Get parent {@link ParallelSystemArrayMediator} object. + */ + getSystemArray(): ParallelSystemArrayMediator | distributed.DistributedSystemArrayMediator; + /** + * @hidden + */ + private complete_history(uid); + /** + * @hidden + */ + protected _replyData(invoke: protocol.Invoke): void; + /** + * @inheritdoc + */ + replyData(invoke: protocol.Invoke): void; + } +} +declare namespace samchon.templates.parallel { + /** + * A mediator server, driver for the master client. + * + * The {@link MediatorServer} is a class opening a server accepting the **master** client, following the protocol of + * Samchon Framework's own. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorServer extends MediatorSystem implements slave.ISlaveServer { + /** + * @hidden + */ + private server_base_; + /** + * @hidden + */ + private port; + /** + * Initializer Constructor. + * + * @param systemArray The parent {@link ParallelSystemArrayMediator} object. + * @param port Port number of server to open. + */ + constructor(systemArray: ParallelSystemArrayMediator, port: number); + /** + * Initializer Constructor. + * + * @param systemArray The parent {@link DistributedSystemArrayMediator} object. + * @param port Port number of server to open. + */ + constructor(systemArray: distributed.DistributedSystemArrayMediator, port: number); + /** + * Factory method creating {@link IServerBase} object. + * + * This method {@link createServerBase createServerBase()} determines which protocol is used in this server, + * {@link MediatorServer}. Note that, **slave** (this {@link MediatorServer} object) must follow the **master**'s + * protocol. + * + * Overrides and return one of them considering the which protocol to follow: + * + * - {@link ServerBase} + * - {@link WebServerBase} + * - {@link SharedWorkerServerBase} + */ + protected createServerBase(): protocol.IServerBase; + /** + * Add a newly connected remote client. + * + * {@link MediatorServer} represents a **slave** dedicating to its **master**. In that reason, the + * {@link MediatorServer} does not accept multiple **master** clients. It accepts only one. Thus, *listener* of + * the *communicator* is {@link MediatorSystem} object, itself. + * + * @param driver A communicator with remote client. + */ + addClient(driver: protocol.IClientDriver): void; + /** + * @inheritdoc + */ + start(): void; + /** + * @inheritdoc + */ + open(port: number): void; + /** + * @inheritdoc + */ + close(): void; + } + /** + * A mediator server, driver for the master client. + * + * The {@link MediatorWebServer} is a class opening a server accepting the **master** client, following the + * web-socket protocol. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorWebServer extends MediatorServer { + /** + * @inheritdoc + */ + protected createServerBase(): protocol.IServerBase; + } + /** + * A mediator server, driver for the master client. + * + * The {@link MediatorSharedWorkerServer} is a class opening a server accepting the **master** client, following the + * SharedWorker's protocol. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorSharedWorkerServer extends MediatorServer { + /** + * @inheritdoc + */ + protected createServerBase(): protocol.IServerBase; + } +} +declare namespace samchon.templates.parallel { + /** + * A mediator client, driver for the master server. + * + * The {@link MediatorServer} is a class being a client connecting to the **master** server, following the protocol + * of Samchon Framework's own. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorClient extends MediatorSystem implements slave.ISlaveClient { + /** + * @hidden + */ + private ip; + /** + * @hidden + */ + private port; + /** + * Initializer Constructor. + * + * @param systemArray The parent {@link ParallelSystemArrayMediator} object. + * @param ip IP address to connect. + * @param port Port number to connect. + */ + constructor(systemArray: ParallelSystemArrayMediator, ip: string, port: number); + /** + * Initializer Constructor. + * + * @param systemArray The parent {@link DistributedSystemArrayMediator} object. + * @param ip IP address to connect. + * @param port Port number to connect. + */ + constructor(systemArray: distributed.DistributedSystemArrayMediator, ip: string, port: number); + /** + * Factory method creating {@link IServerConnector} object. + * + * The {@link createServerConnector createServerConnector()} is an abstract method creating + * {@link IServerConnector} object. Overrides and returns one of them, considering which protocol the **master** + * server follows: + * + * - {@link ServerConnector} + * - {@link WebServerConnector} + * - {@link SharedWorkerServerConnector} + * + * @return A newly created {@link IServerConnector} object. + */ + protected createServerConnector(): protocol.IServerConnector; + /** + * @inheritdoc + */ + start(): void; + /** + * @inheritdoc + */ + connect(): void; + } + /** + * A mediator client, driver for the master server. + * + * The {@link MediatorWebClient} is a class being a client connecting to the **master** server, following the + * web-socket protocol. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorWebClient extends MediatorClient { + /** + * @inheritdoc + */ + protected createServerConnector(): protocol.IServerConnector; + } + /** + * A mediator client, driver for the master server. + * + * The {@link MediatorSharedWorkerClient} is a class being a client connecting to the **master** server, following + * the SharedWorker's protocol. + * + * #### [Inherited] {@link MediatorSystem} + * The {@link MediatorSystem} is an abstract class helping {@link ParallelSystemArrayMediator} can be a **slave** + * system. The {@link MediatorSystem} interacts and communicates with the **master** system as a role of **slave**. + * + * This {@link MediatorSystem} object is created in {@link ParallelSystemArrayMediator.createMediator}. Override the + * method and return one of them, which are derived from this {@link MediatorSystem} class, considering which + * type and protocol the **master** system follows: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * When the **master** orders a *parallel process* to this **slave**, then the {@link MediatorSystem} delivers the + * *parallel process* to its parent {@link ParallelSystemArrayMediator} object. The + * {@link ParallelSystemArrayMediator} object distributes the *parallel process* to its slaves system, + * {@link ParallelSystem} objects. When the *parallel process* has completed, then {@link MediatorSystem} reports the + * result to its **master**. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System), + * [Templates - Distributed System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Distributed_System) + * @author Jeongho Nam + */ + class MediatorSharedWorkerClient extends MediatorClient { + /** + * @inheritdoc + */ + protected createServerConnector(): protocol.IServerConnector; + } +} +declare namespace samchon.templates.parallel { + /** + * History of an {@link Invoke} message. + * + * The {@link PRInvokeHistory} is a class archiving history log of an {@link Invoke} message which requests the + * *parallel process*, created whenever {@link ParallelSystemArray.sendSegmentData} or + * {@link ParallelSystemArray.sendSegmentData} is called. + * + * When the *parallel process* has completed, then {@link complete complete()} is called and the *elapsed time* is + * determined. The elapsed time is utilized for computation of {@link ParallelSystem.getPerformance performance index} + * of each {@link ParallelSystem parallel slave system}. + * + * + * + * + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + class PRInvokeHistory extends protocol.InvokeHistory { + /** + * @hidden + */ + private first; + /** + * @hidden + */ + private last; + /** + * Default Constructor. + */ + constructor(); + /** + * Construct from an {@link Invoke} message. + * + * @param invoke An {@link Invoke} message requesting a *parallel process*. + */ + constructor(invoke: protocol.Invoke); + /** + * Get initial piece's index. + * + * Returns initial piece's index in the section of requested *parallel process*. + * + * @return The initial index. + */ + getFirst(): number; + /** + * Get final piece's index. + * + * Returns initial piece's index in the section of requested *parallel process*. The range used is + * [*first*, *last*), which contains all the pieces' indices between *first* and *last*, including the piece + * pointed by index *first*, but not the piece pointed by the index *last*. + * + * @return The final index. + */ + getLast(): number; + /** + * Compute number of allocated pieces. + */ + computeSize(): number; + } +} +declare namespace samchon.templates.parallel { + /** + * Master of Parallel Processing System, a server accepting slave clients. + * + * The {@link ParallelClientArray} is an abstract class, derived from the {@link ParallelSystemArray} class, opening + * a server accepting {@link ParallelSystem parallel clients}. + * + * Extends this {@link ParallelClientArray}, overrides {@link createServerBase createServerBase()} to determine which + * protocol to follow and {@link createExternalClient createExternalClient()} creating child {@link ParallelSystem} + * object. After the extending and overridings, open this server using the {@link open open()} method. + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        + * important. Only interested in user's perspective is *which can be done*. * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. * *
          *
        • @@ -5135,180 +8824,75 @@ declare namespace samchon.protocol.external { * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the * external system. *
          • - *
        • Those strategy is called Proxy Pattern.
          • + *
        • Those strategy is called *Proxy Pattern*.
          • *
        * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) * @author Jeongho Nam */ - abstract class ExternalSystemArray extends EntityDequeCollection implements IProtocol { - /** - * Default Constructor. - */ - constructor(); + abstract class ParallelClientArray extends ParallelSystemArray implements external.IExternalClientArray { /** * @hidden */ - private handle_system_erase(event); - /** - * Test whether this system array has the role. - * - * @param name Name, identifier of target {@link ExternalSystemRole role}. - * - * @return Whether the role has or not. - */ - hasRole(name: string): boolean; - /** - * Get a role. - * - * @param name Name, identifier of target {@link ExternalSystemRole role}. - * - * @return The specified role. - */ - getRole(name: string): ExternalSystemRole; - /** - *

        Send an {@link Invoke} message.

        - * - * @param invoke An {@link Invoke} message to send. - */ - sendData(invoke: Invoke): void; - /** - *

        Handle an {@Invoke} message have received.

        - * - * @param invoke An {@link Invoke} message have received. - */ - replyData(invoke: Invoke): void; - /** - * Tag name of the {@link ExternalSytemArray} in {@link XML}. - * - * @return systemArray. - */ - TAG(): string; - /** - * Tag name of {@link ExternalSystem children elements} belonged to the {@link ExternalSytemArray} in {@link XML}. - * - * @return system. - */ - CHILD_TAG(): string; - } -} -declare namespace samchon.protocol.parallel { - /** - *

        A manager containing {@link ParallelSystem} objects.

        - * - * - * - * @author Jeongho Nam - */ - abstract class ParallelSystemArray extends external.ExternalSystemArray { - /** - * @hidden - */ - private history_sequence_; - /** - * Default Constructor. - */ - constructor(); - /** - * @inheritdoc - */ - at(index: number): ParallelSystem; - /** - * @hidden - */ - _Fetch_history_sequence(): number; - /** - * @hidden - */ - _Set_history_sequence(val: number): void; - /** - * - * @param invoke An invoke message requesting parallel process. - * @param size Number of pieces. - */ - sendSegmentData(invoke: Invoke, size: number): void; - /** - * - * - * @param invoke An invoke message requesting parallel process. - * @param first Initial piece's index in a section. - * @param last Final piece's index in a section. The ranged used is [first, last), which contains - * all the pieces' indices between first and last, including the piece pointed by index - * first, but not the piece pointed by the index last. - */ - sendPieceData(invoke: Invoke, first: number, last: number): void; - /** - * - * @param history - * - * @return Whether the processes with same uid are all fininsed. - */ - _Complete_history(history: InvokeHistory): boolean; - /** - * @hidden - */ - private normalize_performance(); - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedSystemArray extends parallel.ParallelSystemArray { - /** - * @hidden - */ - private role_map_; - /** - * Default Constructor. - */ - constructor(); - construct(xml: library.XML): void; - abstract createRole(xml: library.XML): DistributedSystemRole; - /** - * @inheritdoc - */ - at(index: number): DistributedSystem; - getRoleMap(): std.HashMap; - /** - * @inheritdoc - */ - hasRole(name: string): boolean; - /** - * @inheritdoc - */ - getRole(name: string): DistributedSystemRole; - insertRole(role: DistributedSystemRole): void; - eraseRole(name: string): void; - toXML(): library.XML; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedClientArray extends DistributedSystemArray implements external.IExternalClientArray { - /** - * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. - */ private server_base_; /** * Default Constructor. */ constructor(); /** - *

        Factory method creating {@link IServerBase} object.

        + * Factory method creating {@link IServerBase} object. * - *

        This method {@link createServerBase createServerBase()} determines which protocol is used in this server, + * This method {@link createServerBase createServerBase()} determines which protocol is used in this server, * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who - * may connect to {@link ExternalClientArray this server} must follow the specified protocol.

        + * may connect to {@link ExternalClientArray this server} must follow the specified protocol. * - *

        Creates and returns one of them:

        - *
          - *
        • {@link ServerBase}
          • - *
        • {@link WebServerBase}
          • - *
        • {@link SharedWorkerServerBase}
          • - *
        + * Overrides the {@link createServerBase createServerBase()} method to create and return one of them: + * + * - {@link ServerBase} + * - {@link WebServerBase} + * - {@link SharedWorkerServerBase} * * @return A new {@link IServerBase} object. */ - protected abstract createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; - createChild(xml: library.XML): DistributedSystem; - protected abstract createExternalClient(driver: IClientDriver): DistributedSystem; + protected abstract createServerBase(): protocol.IServerBase; + /** + * Add a newly connected remote client. + * + * When a {@link IClientDriver remote client} connects to this *master server of parallel processing system*, + * then this {@link ParallelClientArray} creates a child {@link ParallelSystem parallel client} object through + * the {@link createExternalClient createExternalClient()} method and {@link insert inserts} it. + * + * @param driver A communicator for external client. + */ + addClient(driver: protocol.IClientDriver): void; + /** + * (Deprecated) Factory method creating child object. + * + * The method {@link createChild createChild()} is deprecated. Don't use and override this. + * + * Note that, the {@link ParallelClientArray} is a server accepting {@link ParallelSystem parallel clients}. + * There's no way to creating the {@link ParallelSystem parallel clients} in advance before opening the server. + * + * @param xml An {@link XML} object represents the child {@link ParallelSystem} object. + * @return ```null``` + */ + createChild(xml: library.XML): ParallelSystem; + /** + * Factory method creating {@link ParallelSystem} object. + * + * The method {@link createExternalClient createExternalClient()} is a factory method creating a child + * {@link ParallelSystem} object, that is called whenever a parallel client has connected, by + * {@link addClient addClient()}. + * + * Overrides this {@link createExternalClient} method and creates a type of {@link ParallelSystem} object with + * the *driver* that communicates with the parallel client. After the creation, returns the {@link ParallelSystem} + * object. Then whenever a parallel client has connected, matched {@link ParallelSystem} object will be + * constructed and {@link insert inserted} into this {@link ParallelClientArray} object. + * + * @param driver A communicator with the parallel client. + * @return A newly created {@link ParallelSystem} object. + */ + protected abstract createExternalClient(driver: protocol.IClientDriver): ParallelSystem; /** * @inheritdoc */ @@ -5319,389 +8903,208 @@ declare namespace samchon.protocol.distributed { close(): void; } } -declare namespace samchon.protocol.distributed { - abstract class DistributedSystemArrayMediator extends DistributedSystemArray { +declare namespace samchon.templates.parallel { + /** + * Mediator of Parallel Processing System. + * + * The {@link ParallelSystemArrayMediator} class be a **master** for its slave systems, and be a **slave** to its + * master system at the same time. This {@link ParallelSystemArrayMediator} be a **master **system, containing and + * managing {@link ParallelSystem} objects, which represent parallel slave systems, by extending + * {@link ParallelSystemArray} class. Also, be a **slave** system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a **master**, you can specify this {@link ParallelSystemArrayMediator} class to be a master server accepting + * slave clients or a master client to connecting slave servers. Even both of them is possible. Extends one + * of them below and overrides abstract factory method(s) creating the child {@link ParallelSystem} object. + * + * - {@link ParallelClientArrayMediator}: A server accepting {@link ParallelSystem parallel clients}. + * - {@link ParallelServerArrayMediator}: A client connecting to {@link ParallelServer parallel servers}. + * - {@link ParallelServerClientArrayMediator}: Both of them. Accepts {@link ParallelSystem parallel clients} and + * connects to {@link ParallelServer parallel servers} at the same time. + * + * As a **slave**, you can specify this {@link ParallelSystemArrayMediator} to be a client slave connecting to + * master server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + abstract class ParallelSystemArrayMediator extends ParallelSystemArray { + /** + * @hidden + */ private mediator_; /** * Default Constructor. */ constructor(); - protected abstract createMediator(): parallel.MediatorSystem; + /** + * Factory method creating a {@link MediatorSystem} object. + * + * The {@link createMediator createMediator()} is an abstract method creating the {@link MediatorSystem} object. + * + * You know what? this {@link ParallelSystemArrayMediator} class be a **master** for its slave systems, and be a + * **slave** to its master system at the same time. The {@link MediatorSystem} object makes it possible; be a + * **slave** system. This {@link createMediator} determines specific type of the {@link MediatorSystem}. + * + * Overrides the {@link createMediator createMediator()} method to create and return one of them following which + * protocol and which type of remote connection (server or client) will be used: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * @return A newly created {@link MediatorSystem} object. + */ + protected abstract createMediator(): MediatorSystem; + /** + * Start mediator. + * + * If the {@link getMediator mediator} is a type of server, then opens the server accepting master client. + * Otherwise, the {@link getMediator mediator} is a type of client, then connects the master server. + */ protected startMediator(): void; - getMediator(): parallel.MediatorSystem; - _Complete_history(history: parallel.PRInvokeHistory): boolean; + /** + * Get {@link MediatorSystem} object. + * + * When you need to send an {@link Invoke} message to the master system of this + * {@link ParallelSystemArrayMediator}, then send to the {@link MediatorSystem} through this {@link getMediator}. + * + * ```typescript + * this.getMediator().sendData(...); + * ``` + * + * @return The {@link MediatorSystem} object. + */ + getMediator(): MediatorSystem; + /** + * @hidden + */ + protected _Complete_history(history: PRInvokeHistory): boolean; } } -declare namespace samchon.protocol.distributed { - abstract class DistributedClientArrayMediator extends DistributedSystemArrayMediator implements external.IExternalClientArray { - /** - * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. - */ - private server_base_; - /** - * Default Constructor. - */ - constructor(); - /** - *

        Factory method creating {@link IServerBase} object.

        - * - *

        This method {@link createServerBase createServerBase()} determines which protocol is used in this server, - * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who - * may connect to {@link ExternalClientArray this server} must follow the specified protocol.

        - * - *

        Creates and returns one of them:

        - *
          - *
        • {@link ServerBase}
          • - *
        • {@link WebServerBase}
          • - *
        • {@link SharedWorkerServerBase}
          • - *
        - * - * @return A new {@link IServerBase} object. - */ - protected abstract createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; - createChild(xml: library.XML): DistributedSystem; - protected abstract createExternalClient(driver: IClientDriver): DistributedSystem; - /** - * @inheritdoc - */ - open(port: number): void; - /** - * @inheritdoc - */ - close(): void; - } -} -declare namespace samchon.protocol.external { +declare namespace samchon.templates.parallel { /** - *

        An external system driver.

        + * Mediator of Parallel Processing System, a server accepting slave clients. * - *

        The {@link ExternalSystem} class represents an external system, connected and interact with this system. - * {@link ExternalSystem} takes full charge of network communication with external system have connected. - * Replied {@link Invoke messages} from the external system is shifted to and processed in, children elements of this - * class, {@link ExternalSystemRole} objects.

        + * The {@link ParallelClientArrayMediator} is an abstract class, derived from the {@link ParallelSystemArrayMediator} + * class, opening a server accepting {@link ParallelSystem parallel clients} as a **master**. * - *

        a client slave connecting to + * master server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * - * - *

        + * * - *

        Bridge & Proxy Pattern

        - *

        The {@link ExternalSystem} class can be a bridge for logical proxy. In framework within user, - * which {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged - * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        - * - *
          - *
        • - * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring - * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. - *
          • - *
        • - * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call - * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the - * external system. - *
          • - *
        • Those strategy is called Bridge Pattern and Proxy Pattern.
          • - *
        - * - * @author Jeongho Nam - */ - abstract class ExternalSystem extends EntityDequeCollection implements IProtocol { - /** - * The name represents external system have connected. - */ - protected name: string; - /** - * @hidden - */ - private system_array_; - /** - * @hidden - */ - private communicator_; - constructor(systemArray: ExternalSystemArray); - constructor(systemArray: ExternalSystemArray, communicator: IClientDriver); - /** - * Default Destructor. - */ - destructor(): void; - /** - * @hidden - */ - private handle_close(); - getSystemArray(): ExternalSystemArray; - /** - * Identifier of {@link ExternalSystem} is its {@link name}. - */ - key(): string; - /** - * Get {@link name}. - */ - getName(): string; - protected communicator: protocol.ICommunicator; - close(): void; - /** - * Send {@link Invoke} message to external system. - * - * @param invoke An {@link Invoke} message to send. - */ - sendData(invoke: Invoke): void; - /** - * Handle an {@Invoke} message has received. - * - * @param invoke An {@link Invoke} message have received. - */ - replyData(invoke: Invoke): void; - /** - * Tag name of the {@link ExternalSytem} in {@link XML}. - * - * @return system. - */ - TAG(): string; - /** - * Tag name of {@link ExternalSystemRole children elements} belonged to the {@link ExternalSytem} in {@link XML}. - * - * @return role. - */ - CHILD_TAG(): string; - } -} -declare namespace samchon.protocol.parallel { - /** - *

        An external parallel system driver.

        - * - * - * - * @author Jeongho Nam - */ - abstract class ParallelSystem extends external.ExternalSystem { - /** - * @hidden - */ - private progress_list_; - /** - * @hidden - */ - private history_list_; - /** - *

        Performance index.

        - * - *

        A performance index that indicates how much fast the connected parallel system is.

        - * - *

        If this {@link ParallelSystem parallel system} hasn't any {@link Invoke} message had handled, then the - * {@link performance performance index} will be 1, which means default and average value between all - * {@link ParallelSystem} instances (belonged to a same {@link ParallelSystemArray} object).

        - * - *

        You can specify this {@link performance} by yourself, but notice that, if the - * {@link performance performance index} is higher then other {@link ParallelSystem} objects, then this - * {@link ParallelSystem parallel system} will ordered to handle more processes than other - * {@link ParallelSystem} objects. Otherwise, the {@link performance performance index) is lower than others, - * of course, less processes will be delivered.

        - * - *

        This {@link performance index} is always re-calculated whenever {@link ParallelSystemArray} calls one of - * them below.

        - * - *
          - *
        • {@link ParallelSystemArray.sendSegmentData ParallelSystemArray.sendSegmentData()}
          • - *
        • {@link ParallelSystemArray.sendPieceData ParallelSystemArray.sendPieceData()}
          • - *
        - * - *

        If this class is a type of {@link DistributedSystem} derived class from the {@link ParallelSystem}, - * then {@link DistributedSystemRole.sendData DistributedSystemRole.sendData()} also cause the re-calculation. - *

        - */ - protected performance: number; - constructor(systemArray: ParallelSystemArray); - constructor(systemArray: ParallelSystemArray, communicator: IClientDriver); - destructor(): void; - /** - * Get manager of this object, {@link systemArray}. - * - * @return A manager containing this {@link ParallelSystem} object. - */ - getSystemArray(): ParallelSystemArray; - /** - * Get {@link performant performance index}. - * - * A performance index that indicates how much fast the connected parallel system is. - */ - getPerformance(): number; - _Get_progress_list(): std.HashMap>; - _Get_history_list(): std.HashMap; - _Set_performance(val: number): void; - /** - * @hidden - */ - _Send_piece_data(invoke: Invoke, first: number, last: number): void; - /** - * @hidden - */ - private _replyData(invoke); - /** - * - * - * @param xml - * - * @see {@link ParallelSystemArray.notify_complete} - */ - protected _Report_history(xml: library.XML): void; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedSystem extends parallel.ParallelSystem { - destructor(): void; - createChild(xml: library.XML): external.ExternalSystemRole; - /** - * Get manager of this object. - * - * @return A manager containing this {@link DistributedSystem} objects. - */ - getSystemArray(): DistributedSystemArray; - /** - * @inheritdoc - */ - has(key: string): boolean; - /** - * @inheritdoc - */ - get(key: string): DistributedSystemRole; - replyData(invoke: protocol.Invoke): void; - protected _Report_history(xml: library.XML): void; - } -} -declare namespace samchon.protocol.distributed { - interface IDistributedServer extends DistributedSystem, external.IExternalServer { - /** - * @inheritdoc - */ - getSystemArray(): DistributedSystemArray; - /** - * @inheritdoc - */ - has(key: string): boolean; - /** - * @inheritdoc - */ - get(key: string): DistributedSystemRole; - } - abstract class DistributedServer extends DistributedSystem implements external.IExternalServer { - protected ip: string; - protected port: number; - constructor(systemArray: DistributedSystemArray); - protected abstract createServerConnector(): IServerConnector; - connect(): void; - getIP(): string; - getPort(): number; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedServerArray extends DistributedSystemArray implements external.IExternalServerArray { - /** - * Default Constructor. - */ - constructor(); - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedServerArrayMediator extends DistributedSystemArrayMediator implements external.IExternalServerArray { - /** - * Default Constructor. - */ - constructor(); - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedServerClientArray extends DistributedClientArray implements external.IExternalServerClientArray { - /** - * Default Constructor. - */ - constructor(); - createChild(xml: library.XML): DistributedSystem; - protected abstract createExternalServer(xml: library.XML): IDistributedServer; - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.distributed { - abstract class DistributedServerClientArrayMediator extends DistributedClientArrayMediator implements external.IExternalServerClientArray { - /** - * Default Constructor. - */ - constructor(); - createChild(xml: library.XML): DistributedSystem; - protected abstract createExternalServer(xml: library.XML): IDistributedServer; - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.external { - /** - *

        An interface for an {@link ExternalSystemArray} accepts {@link ExternalSystem external clients} as a - * {@link IServer server}.

        - * - *

        The easiest way to defining an {@link ExternalSystemArray} who opens server and accepts - * {@link ExternalSystem external clients} is to extending one of below, who are derived from this interface - * {@link IExternalClientArray}. However, if you can't specify an {@link ExternalSystemArray} to be whether server or - * client, then make a class (let's name it as BaseSystemArray) extending {@link ExternalSystemArray} and make - * a new class (now, I name it BaseClientArray) extending BaseSystemArray and implementing this - * interface {@link IExternalClientArray}. Define the BaseClientArray following those codes on below: - * - *

        - * - * @author Jeongho Nam - */ - interface IExternalClientArray extends ExternalSystemArray, IServer { - } - /** - *

        An {@link ExternalSystemArray} acceepts {@link ExternalSystem external clients} as a {@link IServer server}.

        - * - *

        {@link ExternalServerArray} is an abstract class contains, manages and accepts external server drivers, - * {@link IExternalServer} objects, as a {@link IServer server}.

        - * - *

        - * - *

        - * - *

        Proxy Pattern

        - *

        The {@link ExternalSystemArray} class can use Proxy Pattern. In framework within user, which + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        + * important. Only interested in user's perspective is *which can be done*. * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. * *
          *
        • @@ -5713,14 +9116,15 @@ declare namespace samchon.protocol.external { * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the * external system. *
          • - *
        • Those strategy is called Proxy Pattern.
          • + *
        • Those strategy is called *Proxy Pattern*.
          • *
        * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) * @author Jeongho Nam */ - abstract class ExternalClientArray extends ExternalSystemArray implements IExternalClientArray { + abstract class ParallelClientArrayMediator extends ParallelSystemArrayMediator implements external.IExternalClientArray { /** - * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. + * @hidden */ private server_base_; /** @@ -5728,36 +9132,61 @@ declare namespace samchon.protocol.external { */ constructor(); /** - *

        Factory method creating {@link IServerBase} object.

        + * Factory method creating {@link IServerBase} object. * - *

        This method {@link createServerBase createServerBase()} determines which protocol is used in this server, - * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who - * may connect to {@link ExternalClientArray this server} must follow the specified protocol.

        + * This method {@link createServerBase createServerBase()} determines which protocol is used in this server, + * {@link ParallelClientArrayMediator}. If the protocol is determined, then + * {@link ParallelSystem parallel clients} who may connect to {@link ParallelClientArrayMediator this server} + * must follow the specified protocol. * - *

        Creates and returns one of them:

        - *
          - *
        • {@link ServerBase}
          • - *
        • {@link WebServerBase}
          • - *
        • {@link SharedWorkerServerBase}
          • - *
        + * Overrides the {@link createServerBase createServerBase()} method to create and return one of them: + * + * - {@link ServerBase} + * - {@link WebServerBase} + * - {@link SharedWorkerServerBase} * * @return A new {@link IServerBase} object. */ - protected abstract createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; + protected abstract createServerBase(): protocol.IServerBase; /** - * This method is deprecated. Don't use and override this. + * Add a newly connected remote client. * - * @return null. + * When a {@link IClientDriver remote client} connects to this *master server of parallel processing system*, + * then this {@link ParallelClientArrayMediator} creates a child {@link ParallelSystem parallel client} object + * through the {@link createExternalClient createExternalClient()} method and {@link insert inserts} it. + * + * @param driver A communicator for parallel client. */ - createChild(xml: library.XML): ExternalSystem; + addClient(driver: protocol.IClientDriver): void; /** - * Factory method creating {@link ExternalSystem} object. + * (Deprecated) Factory method creating child object. * - * @param driver A communicator with connected client. - * @return A newly created {@link ExternalSystem} object. + * The method {@link createChild createChild()} is deprecated. Don't use and override this. + * + * Note that, the {@link ParallelClientArrayMediator} is a server accepting {@link ParallelSystem parallel + * clients} as a master. There's no way to creating the {@link ParallelSystem parallel clients} in advance before + * opening the server. + * + * @param xml An {@link XML} object represents the child {@link ParallelSystem} object. + * @return null */ - protected abstract createExternalClient(driver: IClientDriver): ExternalSystem; + createChild(xml: library.XML): ParallelSystem; + /** + * Factory method creating {@link ParallelSystem} object. + * + * The method {@link createExternalClient createExternalClient()} is a factory method creating a child + * {@link ParallelSystem} object, that is called whenever a parallel client has connected, by + * {@link addClient addClient()}. + * + * Overrides this {@link createExternalClient} method and creates a type of {@link ParallelSystem} object with + * the *driver* that communicates with the parallel client. After the creation, returns the {@link ParallelSystem} + * object. Then whenever a parallel client has connected, matched {@link ParallelSystem} object will be + * constructed and {@link insert inserted} into this {@link ParallelClientArrayMediator} object. + * + * @param driver A communicator with the parallel client. + * @return A newly created {@link ParallelSystem} object. + */ + protected abstract createExternalClient(driver: protocol.IClientDriver): ParallelSystem; /** * @inheritdoc */ @@ -5768,58 +9197,78 @@ declare namespace samchon.protocol.external { close(): void; } } -declare namespace samchon.protocol.external { +declare namespace samchon.templates.parallel { /** - *

        An interface for an external server driver.

        + * An interface for a parallel slave server driver. * - *

        The easiest way to defining an external server driver is to extending one of below, who are derived from this - * interface {@link IExternalServer}. However, if you've to interact with an external system who can be both server - * and client, then make a class (let's name it as BaseSystem) extending {@link ExternalSystem} and make a - * new class (now, I name it BaseServer) extending BaseSystem and implementing this interface - * {@link IExternalServer}. Define the BaseServer following those codes on below: + * The easiest way to defining a driver for parallel **slave** server is extending {@link ParallelServer} class. + * However, if you've to interact with a prallel **slave** system who can be both server and client, them make a class + * (let's name it **BaseSystem**) extending the {@link ParallelSystem} class. At next, make a new class (now, I name it + * **BaseServer**) extending the **BaseSystem** and implements this interface {@link IParallelServer}. Define the + * **BaseServer** following those codes on below: * *

        * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) * @author Jeongho Nam */ - interface IExternalServer extends ExternalSystem { + interface IParallelServer extends ParallelSystem { + /** + * Connect to slave server. + */ connect(): void; } /** - *

        An external server driver.

        + * A driver for parallel slave server. * - *

        The {@link ExternalServer} class represents an external server, connected and interact with this system. - * {@link ExternalServer} takes full charge of network communication with external server have connected. - * Replied {@link Invoke messages} from the external system is shifted to and processed in, children elements of this - * class, {@link ExternalSystemRole} objects.

        + * The {@link ParallelServer} is an abstract class, derived from the {@link ParallelSystem} class, connecting to + * remote, parallel **slave** server. Extends this {@link ParallelServer} class and overrides the + * {@link createServerConnector createServerConnector()} method following which protocol the **slave** server uses. * - *

        - * - *

        + * * - *

        Bridge & Proxy Pattern

        - *

        The {@link ExternalSystem} class can be a bridge for logical proxy. In framework within user, + * #### Bridge & Proxy Pattern + * This class {@link ParallelSystem} is derived from the {@link ExternalSystem} class. Thus, you can take advantage + * of the *Bridge & Proxy Pattern* in this {@link ParallelSystem} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Bridge & Proxy Pattern*: + * + * The {@link ExternalSystem} class can be a *bridge* for *logical proxy*. In framework within user, * which {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        + * important. Only interested in user's perspective is *which can be done*. * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. * *
          *
        • @@ -5831,12 +9280,13 @@ declare namespace samchon.protocol.external { * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the * external system. *
          • - *
        • Those strategy is called Bridge Pattern and Proxy Pattern.
          • + *
        • Those strategy is called *Bridge Pattern* and *Proxy Pattern*.
          • *
        * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) * @author Jeongho Nam */ - abstract class ExternalServer extends ExternalSystem implements IExternalServer { + abstract class ParallelServer extends ParallelSystem implements IParallelServer { /** * IP address of target external system to connect. */ @@ -5846,431 +9296,94 @@ declare namespace samchon.protocol.external { */ protected port: number; /** - * Default Constructor. - */ - constructor(systemArray: ExternalSystemArray); - /** - * Factory method creating server connector. - */ - protected abstract createServerConnector(): IServerConnector; - /** - * @inheritdoc - */ - connect(): void; - /** - * @inheritdoc - */ - getIP(): string; - /** - * @inheritdoc - */ - getPort(): number; - } -} -declare namespace samchon.protocol.external { - /** - *

        An interface for an {@link ExternalSystemArray} connects to {@link IExternalServer external servers} as a - * client.

        - * - *

        The easiest way to defining an {@link ExternalSystemArray} who connects to - * {@link IExternalServer external servers} is to extending one of below, who are derived from this interface - * {@link IExternalServerArray}. However, if you can't specify an {@link ExternalSystemArray} to be whether server or - * client, then make a class (let's name it as BaseSystemArray) extending {@link ExternalSystemArray} and make - * a new class (now, I name it BaseServerArray) extending BaseSystemArray and implementing this - * interface {@link IExternalServerArray}. Define the BaseServerArray following those codes on below: - * - *

        - * - * @author Jeongho Nam - */ - interface IExternalServerArray extends ExternalSystemArray { - /** - *

        Connect to {@link IExternalServer external servers}.

        + * Construct from parent {@link ParallelSystemArray}. * - *

        This method calls children elements' method {@link IExternalServer.connect} gradually.

        + * @param systemArray The parent {@link ParallelSystemArray} object. */ - connect(): void; - } - /** - *

        An {@link ExternalSystemArray} connecting to {@link IExternalServer external servers} as a client.

        - * - *

        {@link ExternalServerArray} is an abstract class contains, manages and connects to external server drivers, - * {@link IExternalServer} objects, as a client.

        - * - *

        - * - *

        - * - *

        Proxy Pattern

        - *

        The {@link ExternalSystemArray} class can use Proxy Pattern. In framework within user, which - * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        - * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged - * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        - * - *
          - *
        • - * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring - * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. - *
          • - *
        • - * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call - * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the - * external system. - *
          • - *
        • Those strategy is called Proxy Pattern.
          • - *
        - * - * @author Jeongho Nam - */ - abstract class ExternalServerArray extends ExternalSystemArray { - /** - * Default Constructor. - */ - constructor(); - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.external { - /** - *

        An interface for an {@link ExternalSystemArray} accepts {@link ExternalSystem external clients} as a - * {@link IServer server} and connects to {@link IExternalServer} as client, at the same time.

        - * - *

        The easiest way to defining an {@link IExternalServerClientArray} who opens server, accepts - * {@link ExternalSystem external clients} and connects to {@link IExternalServer external servers} is to extending - * one of below, who are derived from this interface {@link IExternalServerClientArray}. However, if you can't - * specify an {@link ExternalSystemArray} to be whether server or client or even can both them, then make a class - * (let's name it as BaseSystemArray) extending {@link ExternalSystemArray} and make a new class (now, I name - * it BaseServerClientArray) extending BaseSystemArray and implementing this interface - * {@link IExternalServerClientArray}. Define the BaseServerClientArray following those codes on below: - * - *

        - * - * @author Jeongho Nam - */ - interface IExternalServerClientArray extends IExternalServerArray, IExternalClientArray { - } - /** - *

        An {@link ExternalSystemArray} connecting to {@link IExternalServer external servers} as a client and - * accepts {@link ExternalSystem external clients} as a {@link IServer server}.

        - * - *

        {@link ExternalServerArray} is an abstract class contains, manages and connects to external server drivers, - * {@link IExternalServer} objects and accepts external client drivers {@link ExternalSyste} obejcts as a - * client and a {@link IServer server} at the same time.

        - * - *

        - * - *

        - * - *

        Proxy Pattern

        - *

        The {@link ExternalSystemArray} class can use Proxy Pattern. In framework within user, which - * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not - * important. Only interested in user's perspective is which can be done.

        - * - *

        By using the logical proxy, user dont't need to know which {@link ExternalSystemRole role} is belonged - * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. - * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}.

        - * - *
          - *
        • - * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring - * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. - *
          • - *
        • - * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call - * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the - * external system. - *
          • - *
        • Those strategy is called Proxy Pattern.
          • - *
        - * - * @author Jeongho Nam - */ - abstract class ExternalServerClientArray extends ExternalClientArray implements IExternalServerClientArray { - /** - * Default Constructor. - */ - constructor(); - /** - *

        Factory method of a child Entity.

        - * - *

        This method is migrated to {@link createExternalServer createExternalServer()}. Override the - * {@link createExternalServer createExternalServer()}.

        - * - * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. - * - * @return A new child Entity via {@link createExternalServer createExternalServer()}. - */ - createChild(xml: library.XML): ExternalSystem; - /** - * Factory method creating an {@link IExternalServer} object. - * - * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. - * - * @return A newly created {@link IExternalServer} object. - */ - protected abstract createExternalServer(xml: library.XML): IExternalServer; - /** - * @inheritdoc - */ - connect(): void; - } -} -declare namespace samchon.protocol.slave { - abstract class SlaveSystem implements protocol.IProtocol { - protected communicator_: ICommunicator; - /** - * Default Constructor. - */ - constructor(); - sendData(invoke: Invoke): void; - protected _replyData(invoke: Invoke): void; - replyData(invoke: Invoke): void; - } -} -declare namespace samchon.protocol.parallel { - abstract class MediatorSystem extends slave.SlaveSystem { - private mediator_; - private progress_list_; - constructor(systemArray: ParallelSystemArrayMediator | distributed.DistributedSystemArrayMediator); - abstract start(): void; - getMediator(): ParallelSystemArrayMediator | distributed.DistributedSystemArrayMediator; - _Complete_history(uid: number): void; - protected _replyData(invoke: Invoke): void; - replyData(invoke: protocol.Invoke): void; - } -} -declare namespace samchon.protocol.parallel { - class MediatorServer extends MediatorSystem implements slave.ISlaveServer { - private server_base_; - private port; - constructor(systemArray: ParallelSystemArrayMediator, port: number); - protected createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; - start(): void; - open(port: number): void; - close(): void; - } - class MediatorWebServer extends MediatorServer { - /** - * @inheritdoc - */ - protected createServerBase(): IServerBase; - } - class MediatorSharedWorkerServer extends MediatorServer { - /** - * @inheritdoc - */ - protected createServerBase(): IServerBase; - } -} -declare namespace samchon.protocol.parallel { - class MediatorClient extends MediatorSystem implements slave.ISlaveClient { - protected ip: string; - protected port: number; - constructor(systemArray: ParallelSystemArrayMediator, ip: string, port: number); - protected createServerConnector(): IServerConnector; - getIP(): string; - getPort(): number; - start(): void; - connect(): void; - } - class MediatorWebClient extends MediatorClient { - /** - * @inheritdoc - */ - protected createServerConnector(): IServerConnector; - } - class MediatorSharedWorkerClient extends MediatorClient { - /** - * @inheritdoc - */ - protected createServerConnector(): IServerConnector; - } -} -declare namespace samchon.protocol.parallel { - class PRInvokeHistory extends InvokeHistory { - /** - * Index number of initial piece. - */ - private first; - /** - * Index number of final piece. - */ - private last; - /** - * Default Constructor. - */ - constructor(); - /** - * Construct from an Invoke message. - * - * @param invoke - */ - constructor(invoke: Invoke); - getFirst(): number; - getLast(): number; - _Set_first(val: number): void; - _Set_last(val: number): void; - /** - * Compute number of allocated pieces. - */ - computeSize(): number; - } -} -declare namespace samchon.protocol.parallel { - abstract class ParallelClientArray extends ParallelSystemArray implements external.IExternalClientArray { - /** - * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. - */ - private server_base_; - /** - * Default Constructor. - */ - constructor(); - /** - *

        Factory method creating {@link IServerBase} object.

        - * - *

        This method {@link createServerBase createServerBase()} determines which protocol is used in this server, - * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who - * may connect to {@link ExternalClientArray this server} must follow the specified protocol.

        - * - *

        Creates and returns one of them:

        - *
          - *
        • {@link ServerBase}
          • - *
        • {@link WebServerBase}
          • - *
        • {@link SharedWorkerServerBase}
          • - *
        - * - * @return A new {@link IServerBase} object. - */ - protected abstract createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; - createChild(xml: library.XML): ParallelSystem; - protected abstract createExternalClient(driver: IClientDriver): ParallelSystem; - /** - * @inheritdoc - */ - open(port: number): void; - /** - * @inheritdoc - */ - close(): void; - } -} -declare namespace samchon.protocol.parallel { - abstract class ParallelSystemArrayMediator extends ParallelSystemArray { - private mediator_; - /** - * Default Constructor. - */ - constructor(); - protected abstract createMediator(): MediatorSystem; - protected start_mediator(): void; - getMediator(): MediatorSystem; - _Complete_history(history: PRInvokeHistory): boolean; - } -} -declare namespace samchon.protocol.parallel { - abstract class ParallelClientArrayMediator extends ParallelSystemArrayMediator implements external.IExternalClientArray { - /** - * A subrogator of {@link IServer server}'s role instead of this {@link ExternalClientArray}. - */ - private server_base_; - /** - * Default Constructor. - */ - constructor(); - /** - *

        Factory method creating {@link IServerBase} object.

        - * - *

        This method {@link createServerBase createServerBase()} determines which protocol is used in this server, - * {@link ExternalClientArray}. If the protocol is determined, then {@link ExternalSystem external clients} who - * may connect to {@link ExternalClientArray this server} must follow the specified protocol.

        - * - *

        Creates and returns one of them:

        - *
          - *
        • {@link ServerBase}
          • - *
        • {@link WebServerBase}
          • - *
        • {@link SharedWorkerServerBase}
          • - *
        - * - * @return A new {@link IServerBase} object. - */ - protected abstract createServerBase(): IServerBase; - addClient(driver: IClientDriver): void; - createChild(xml: library.XML): ParallelSystem; - protected abstract createExternalClient(driver: IClientDriver): ParallelSystem; - /** - * @inheritdoc - */ - open(port: number): void; - /** - * @inheritdoc - */ - close(): void; - } -} -declare namespace samchon.protocol.parallel { - interface IParallelServer extends external.IExternalServer, ParallelSystem { - /** - * @inheritdoc - */ - getSystemArray(): ParallelSystemArray; - } - abstract class ParallelServer extends ParallelSystem implements external.IExternalServer { - protected ip: string; - protected port: number; constructor(systemArray: ParallelSystemArray); - protected abstract createServerConnector(): IServerConnector; + /** + * Factory method creating {@link IServerConnector} object. + * + * The {@link createServerConnector createServerConnector()} is an abstract method creating + * {@link IServerConnector} object. Overrides and returns one of them, considering which protocol the slave server + * follows: + * + * - {@link ServerConnector} + * - {@link WebServerConnector} + * - {@link SharedWorkerServerConnector} + * + * @return A newly created {@link IServerConnector} object. + */ + protected abstract createServerConnector(): protocol.IServerConnector; + /** + * @inheritdoc + */ connect(): void; - getIP(): string; - getPort(): number; } } -declare namespace samchon.protocol.parallel { +declare namespace samchon.templates.parallel { + /** + * Master of Parallel Processing System, a client connecting to slave servers. + * + * The {@link ParallelServerArray} is an abstract class, derived from the {@link ParallelSystemArray} class, + * connecting to {@link IParallelServer parallel servers}. + * + * Extends this {@link ParallelServerArray} and overrides {@link createChild createChild()} method creating child + * {@link IParallelServer} object. After the extending and overriding, construct children {@link IParallelServer} + * objects and call the {@link connect connect()} method. + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ abstract class ParallelServerArray extends ParallelSystemArray implements external.IExternalServerArray { - constructor(); - connect(): void; - } -} -declare namespace samchon.protocol.parallel { - abstract class ParallelServerArrayMediator extends ParallelSystemArrayMediator implements external.IExternalServerArray { + /** + * Default Constructor. + */ constructor(); /** * @inheritdoc @@ -6278,24 +9391,189 @@ declare namespace samchon.protocol.parallel { connect(): void; } } -declare namespace samchon.protocol.parallel { +declare namespace samchon.templates.parallel { + /** + * Mediator of Parallel Processing System, a client connecting to slave servers. + * + * The {@link ParallelServerArrayMediator} is an abstract class, derived from the {@link ParallelSystemArrayMediator} + * class, connecting to {@link IParallelServer parallel servers}. + * + * Extends this {@link ParallelServerArrayMediator} and overrides {@link createChild createChild()} method creating + * child {@link IParallelServer} object. After the extending and overriding, construct children + * {@link IParallelServer} objects and call the {@link connect connect()} method. + * + * #### [Inherited] {@link ParallelSystemArrayMediator} + * The {@link ParallelSystemArrayMediator} class be a **master** for its slave systems, and be a **slave** to its + * master system at the same time. This {@link ParallelSystemArrayMediator} be a **master **system, containing and + * managing {@link ParallelSystem} objects, which represent parallel slave systems, by extending + * {@link ParallelSystemArray} class. Also, be a **slave** system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a **master**, you can specify this {@link ParallelSystemArrayMediator} class to be a master server accepting + * slave clients or a master client to connecting slave servers. Even both of them is possible. Extends one + * of them below and overrides abstract factory method(s) creating the child {@link ParallelSystem} object. + * + * - {@link ParallelClientArrayMediator}: A server accepting {@link ParallelSystem parallel clients}. + * - {@link ParallelServerArrayMediator}: A client connecting to {@link ParallelServer parallel servers}. + * - {@link ParallelServerClientArrayMediator}: Both of them. Accepts {@link ParallelSystem parallel clients} and + * connects to {@link ParallelServer parallel servers} at the same time. + * + * As a **slave**, you can specify this {@link ParallelSystemArrayMediator} to be a client slave connecting to + * master server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + abstract class ParallelServerArrayMediator extends ParallelSystemArrayMediator implements external.IExternalServerArray { + /** + * Default Constructor. + */ + constructor(); + /** + * @inheritdoc + */ + connect(): void; + } +} +declare namespace samchon.templates.parallel { + /** + * Master of Parallel Processing System, be a server and client at the same time. + * + * The {@link ParallelServerClientArray} is an abstract class, derived from the {@link ParallelSystemArray} class, + * opening a server accepting {@link ParallelSystem parallel clients} and being a client connecting to + * {@link IParallelServer parallel servers} at the same time. + * + * Extends this {@link ParallelServerClientArray} and overrides below methods. After the overridings, open server + * with {@link open open()} method and connect to {@link IParallelServer parallel servers} through the + * {@link connect connect()} method. + * + * - {@link createServerBase createServerBase()} + * - {@link createExternalClient createExternalClient()} + * - {@link createExternalServer createExternalServer()} + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ abstract class ParallelServerClientArray extends ParallelClientArray implements external.IExternalServerClientArray { /** * Default Constructor. */ constructor(); - createChild(xml: library.XML): ParallelSystem; - protected abstract createExternalServer(xml: library.XML): IParallelServer; - connect(): void; - } -} -declare namespace samchon.protocol.parallel { - abstract class ParallelServerClientArrayMediator extends ParallelClientArrayMediator implements external.IExternalServerClientArray { /** - * Default Constructor. + * Factory method of a child Entity. + * + * This method is migrated to {@link createExternalServer}. Override the {@link createExternalServer} method. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A new child Entity via {@link createExternalServer createExternalServer()}. + */ + createChild(xml: library.XML): IParallelServer; + /** + * Factory method creating an {@link IParallelServer} object. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A newly created {@link IParallelServer} object. */ - constructor(); - createChild(xml: library.XML): ParallelSystem; protected abstract createExternalServer(xml: library.XML): IParallelServer; /** * @inheritdoc @@ -6303,30 +9581,336 @@ declare namespace samchon.protocol.parallel { connect(): void; } } -declare namespace samchon.protocol.service { - abstract class Client implements protocol.IProtocol { - private user_; - private service_; - private communicator_; - private no_; +declare namespace samchon.templates.parallel { + /** + * Mediator of Parallel Processing System, be a server and client at the same time as a **master**. + * + * The {@link ParallelServerClientArrayMediator} is an abstract class, derived from the + * {@link ParallelSystemArrayMediator} class, opening a server accepting {@link ParallelSystem parallel clients} and + * being a client connecting to {@link IParallelServer parallel servers} at the same time. + * + * Extends this {@link ParallelServerClientArrayMediator} and overrides below methods. After the overridings, open + * server with {@link open open()} method and connect to {@link IParallelServer parallel servers} through the + * {@link connect connect()} method. + * + * - {@link createServerBase createServerBase()} + * - {@link createExternalClient createExternalClient()} + * - {@link createExternalServer createExternalServer()} + * + * #### [Inherited] {@link ParallelSystemArrayMediator} + * The {@link ParallelSystemArrayMediator} class be a **master** for its slave systems, and be a **slave** to its + * master system at the same time. This {@link ParallelSystemArrayMediator} be a **master **system, containing and + * managing {@link ParallelSystem} objects, which represent parallel slave systems, by extending + * {@link ParallelSystemArray} class. Also, be a **slave** system through {@link getMediator mediator} object, which is + * derived from the {@link SlavSystem} class. + * + * As a **master**, you can specify this {@link ParallelSystemArrayMediator} class to be a master server accepting + * slave clients or a master client to connecting slave servers. Even both of them is possible. Extends one + * of them below and overrides abstract factory method(s) creating the child {@link ParallelSystem} object. + * + * - {@link ParallelClientArrayMediator}: A server accepting {@link ParallelSystem parallel clients}. + * - {@link ParallelServerArrayMediator}: A client connecting to {@link ParallelServer parallel servers}. + * - {@link ParallelServerClientArrayMediator}: Both of them. Accepts {@link ParallelSystem parallel clients} and + * connects to {@link ParallelServer parallel servers} at the same time. + * + * As a **slave**, you can specify this {@link ParallelSystemArrayMediator} to be a client slave connecting to + * master server or a server slave accepting master client by overriding the {@link createMediator} method. + * Overrides the {@link createMediator createMediator()} method and return one of them: + * + * - A client slave connecting to master server: + * - {@link MediatorClient} + * - {@link MediatorWebClient} + * - {@link MediatorSharedWorkerClient} + * - A server slave accepting master client: + * - {@link MediatorServer} + * - {@link MediatorWebServer} + * - {@link MediatorSharedWorkerServer} + * + * #### [Inherited] {@link ParallelSystemArray} + * The {@link ParallelSystemArray} is an abstract class containing and managing remote parallel **slave** system + * drivers, {@link ParallelSystem} objects. Within framework of network, {@link ParallelSystemArray} represents your + * system, a **Master** of *Parallel Processing System* that requesting *parallel process* to slave systems and the + * children {@link ParallelSystem} objects represent the remote slave systems, who is being requested the + * *parallel processes*. + * + * When you need the **parallel process**, then call one of them: {@link sendSegmentData} or {@link sendPieceData}. + * When the **parallel process** has completed, {@link ParallelSystemArray} estimates each {@link ParallelSystem}'s + * {@link ParallelSystem.getPerformance performance index} basis on their execution time. Those performance indices + * will be reflected to the next **parallel process**, how much pieces to allocate to each {@link ParallelSystem}. + * + * + * + * + * + * #### Proxy Pattern + * This class {@link ParallelSystemArray} is derived from the {@link ExternalSystemArray} class. Thus, you can take + * advantage of the *Proxy Pattern* in the {@link ParallelSystemArray} class. If a process to request is not the + * *parallel process* (to be distrubted to all slaves), but the **exclusive process** handled in a system, then it + * may better to utilizing the *Proxy Pattern*: + * + * The {@link ExternalSystemArray} class can use *Proxy Pattern*. In framework within user, which + * {@link ExternalSystem external system} is connected with {@link ExternalSystemArray this system}, it's not + * important. Only interested in user's perspective is *which can be done*. + * + * By using the *logical proxy*, user dont't need to know which {@link ExternalSystemRole role} is belonged + * to which {@link ExternalSystem system}. Just access to a role directly from {@link ExternalSystemArray.getRole}. + * Sends and receives {@link Invoke} message via the {@link ExternalSystemRole role}. + * + *
          + *
        • + * {@link ExternalSystemRole} can be accessed from {@link ExternalSystemArray} directly, without inteferring + * from {@link ExternalSystem}, with {@link ExternalSystemArray.getRole}. + *
          • + *
        • + * When you want to send an {@link Invoke} message to the belonged {@link ExternalSystem system}, just call + * {@link ExternalSystemRole.sendData ExternalSystemRole.sendData()}. Then, the message will be sent to the + * external system. + *
          • + *
        • Those strategy is called *Proxy Pattern*.
          • + *
        + * + * @handbook [Templates - Parallel System](https://github.com/samchon/framework/wiki/TypeScript-Templates-Parallel_System) + * @author Jeongho Nam + */ + abstract class ParallelServerClientArrayMediator extends ParallelClientArrayMediator implements external.IExternalServerClientArray { /** - * Construct from an User and WebClientDriver. + * Default Constructor. */ - constructor(user: User, driver: WebClientDriver); - protected abstract createService(path: string): Service; - close(): void; - getUser(): User; - getService(): Service; - getNo(): number; - _Set_no(val: number): void; - sendData(invoke: protocol.Invoke): void; - replyData(invoke: protocol.Invoke): void; - protected changeService(path: string): void; + constructor(); + /** + * Factory method of a child Entity. + * + * This method is migrated to {@link createExternalServer}. Override the {@link createExternalServer} method. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A new child Entity via {@link createExternalServer createExternalServer()}. + */ + createChild(xml: library.XML): ParallelSystem; + /** + * Factory method creating an {@link IParallelServer} object. + * + * @param xml An {@link XML} object represents child element, so that can identify the type of child to create. + * @return A newly created {@link IParallelServer} object. + */ + protected abstract createExternalServer(xml: library.XML): IParallelServer; + /** + * @inheritdoc + */ + connect(): void; } } -declare namespace samchon.protocol.service { - abstract class Server extends protocol.WebServer implements IProtocol { +declare namespace samchon.templates.service { + /** + * A driver of remote client. + * + * The {@link Client} is an abstract class representing and interacting with a remote client. It deals the network + * communication with the remote client and shifts {@link Invoke} message to related {@link User} and {@link Service} + * objects. + * + * Extends this {@link Client} class and override the {@link createService} method, a factory method creating a child + * {@link Service} object. Note that, {@link Client} represents a remote client, not *an user*, a specific *web page* + * or *service*. Do not define logics about user or account information. It must be declared in the parent + * {@link User} class. Also, don't define processes of a specific a web page or service. Defines them in the child + * {@link Service} class. + * + * + * + * + * + * @handbook [Templates - Cloud Service](https://github.com/samchon/framework/wiki/TypeScript-Templates-Cloud_Service) + * @author Jeongho Nam + */ + abstract class Client implements protocol.IProtocol { + /** + * @hidden + */ + private user_; + /** + * @hidden + */ + private no_; + /** + * @hidden + */ + private communicator_; + /** + * @hidden + */ + private service_; + /** + * Construct from parent {@link User} and communicator. + * + * @param user Parent {@link User} object. + * @param driver Communicator with remote client. + */ + constructor(user: User, driver: protocol.WebClientDriver); + /** + * Default Destructor. + * + * This {@link destructor destructor()} method is called when the {@link Client} object is destructed and this + * {@link Client} object is destructed when connection with the remote client is closed or this {@link Client} + * object is {@link User.erase erased} from its parent {@link User} object. + * + * Note that, don't call this {@link destructor destructor()} method by yourself. It must be called automatically + * by those *destruction* cases. Also, if your derived {@link Client} class has something to do on the + * *destruction*, then overrides this {@link destructor destructor()} method and defines the something to do. + * Overriding this {@link destructor destructor()}, don't forget to calling ```super.destructor();``` on tail. + * + * ```typescript + * class MyUser extends protocol.service.Client + * { + * protected destructor(): void + * { + * // DO SOMETHING + * this.do_something(); + * + * // CALL SUPER.DESTRUCTOR() ON TAIL. DON'T FORGET THIS + * super.destructor(); + * } + * } + * ``` + */ + protected destructor(): void; + /** + * Factory method creating {@link Service} object. + * + * @param path Requested path. + * @return A newly created {@link Service} object or ```null```. + */ + protected abstract createService(path: string): Service; + /** + * Close connection. + */ + close(): void; + /** + * Get parent {@link User} object. + * + * Get the parent {@link User} object, who is groupping {@link Client} objects with same session id. + * + * @return The parent {@link User} object. + */ + getUser(): User; + /** + * Get child {@link Service} object. + * + * @return The child {@link Service} object. + */ + getService(): Service; + /** + * Get sequence number. + * + * Get sequence number of this {@link Client} object in the parent {@link User} object. This sequence number also + * be a *key* in the parent {@link User} object, who extended the ```std.HashMap```. + * + * @return Sequence number. + */ + getNo(): number; + /** + * Change related {@link Service} object. + * + * @param path Requested, identifier path. + */ + protected changeService(path: string): void; + /** + * Change {@link Service} to another. + * + * @param service {@link service} object to newly assigned. + */ + protected changeService(service: Service): void; + /** + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message to remote client. + * + * @param invoke An {@link Invoke} messgae to send to remote client. + */ + sendData(invoke: protocol.Invoke): void; + /** + * Handle a replied {@link Invoke} message. + * + * The default {@link Client.replyData Client.replyData()} shifts chain to its parent {@link User} and belonged + * {@link Service} objects, by calling the the {@link User.replyData User.replyData()} and + * {@link Service.replyData Service.replyData()} methods. + * + * Note that, {@link Client} represents a remote client, not *an user*, a specific *web page* or *service*. Do not + * define logics about user or account information. It must be declared in the parent {@link User} class. Also, + * don't define processes of a specific a web page or service. Defines them in the child {@link Service} class. + * + * ```typescript + * class protocol.service.Client + * { + * public replyData(invoke: protocol.Invoke): void + * { + * // SHIFT TO PARENT USER + * // THE PARENT USER ALSO MAY SHIFT TO ITS PARENT SERVER + * this.getUser().replyData(invoke); + * + * // SHIFT TO BELOGED SERVICE + * if (this.getService() != null) + * this.getService().replyData(invoke); + * } + * } + * + * class MyClient extends protocol.service.Client + * { + * public replyData(invoke: protocol.Invoke): void + * { + * if (invoke.getListener() == "do_something_in_client_level") + * this.do_something_in_client_level(); + * else + * super.replyData(invoke); + * } + * } + * ``` + * + * @param invoke An {@link Invoke invoke} message to be handled in {@link Client} level. + */ + replyData(invoke: protocol.Invoke): void; + } +} +/** + * A system template for Cloud Service. + * + * @handbook [Templates - Cloud Service](https://github.com/samchon/framework/wiki/TypeScript-Templates-Cloud_Service) + * @author Jeongho Nam + */ +declare namespace samchon.templates.service { + /** + * A cloud server. + * + * The {@link Server} is an abstract server class, who can build a real-time cloud server, that is following the + * web-socket protocol. Extends this {@link Server} and related classes and overrides abstract methods under below. + * After the overridings, open this {@link Server cloud server} using the {@link open open()} method. + * + * - Objects in composite relationship and their factory methods + * - {@link User}: {@link Server.createUser Server.createUser()} + * - {@link Client}: {@link User.createClient User.createClient()} + * - {@link Service}: {@liok Client.createService Client.createService()} + * - {@link Invoke} message chains; {@link IProtocol.replyData replyData} + * - {@link Server.replyData} + * - {@link User.replyData} + * - {@link Client.replyData} + * - {@link Service.replyData} + * + * + * + * + * + * @handbook [Templates - Cloud Service](https://github.com/samchon/framework/wiki/TypeScript-Templates-Cloud_Service) + * @author Jeongho Nam + */ + abstract class Server extends protocol.WebServer implements protocol.IProtocol { + /** + * @hidden + */ private session_map_; + /** + * @hidden + */ private account_map_; /** * Default Constructor. @@ -6338,80 +9922,348 @@ declare namespace samchon.protocol.service { * @return A newly created {@link User} object. */ protected abstract createUser(): User; - has(account: string): boolean; - get(account: string): User; + /** + * Test wheter an {@link User} exists with the *accountID*. + * + * @param accountID Account id of {@link User} to find. + * @return Exists or not. + */ + has(accountID: string): boolean; + /** + * Get an {@link User} object by its *accountID*. + * + * @param accountID Account id of {@link User} to get. + * @return An {@link User} object. + */ + get(accountID: string): User; + /** + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message to all remote clients through the belonged {@link User} and {@link Client} + * objects. Sending the {@link Invoke} message to all remote clients, it's came true by passing through + * {@link User.sendData User.sendData()}. And the {@link User.sendData} also pass through the + * {@link Client.sendData Client.sendData()}. + * + * ```typescript + * class protocol.service.Server + * { + * public sendData(invoke: Invoke): void + * { + * for (user: User in this) + * for (client: Client in user) + * client.sendData(invoke); + * } + * } + * ``` + * + * @param invoke {@link Invoke} message to send to all remote clients. + */ + sendData(invoke: protocol.Invoke): void; + /** + * Handle a replied {@link Invoke} message. + * + * The {@link Server.replyData Server.replyData()} is an abstract method that handling {@link Invoke} message + * that should be handled in the {@link Server} level. Overrides this {@link replyData replyData()} method and + * defines what to do with the {@link Invoke} message in this {@link Server} level. + * + * @param invoke An {@link Invoke invoke} message to be handled in {@link Server} level. + */ + abstract replyData(invoke: protocol.Invoke): void; + /** + * Add a newly connected remote client. + * + * When a {@link WebClientDriver remote client} connects to this cloud server, then {@link Server} queries the + * {WebClientDriver.getSessionID session id} of the {@link WebClientDriver remote client}. If the + * {WebClientDriver.getSessionID session id} is new one, then creates a new {@link User} object. + * + * At next, creates a {@link Client} object who represents the newly connected remote client and insert the + * {@link Client} object to the matched {@link User} object which is new or ordinary one following the + * {WebClientDriver.getSessionID session id}. At last, a {@link Service} object can be created with referencing + * the {@link WebClientDriver.getPath path}. + * + * List of objects can be created by this method. + * - {@link User} by {@link createUser createUser()}. + * - {@link Client} by {@link User.createClient User.createClient()}. + * - {@link Service} by {@link Client.createService Client.createService()}. + * + * @param driver A web communicator for remote client. + */ + addClient(driver: protocol.WebClientDriver): void; /** * @hidden */ - _Get_account_map(): std.HashMap; - sendData(invoke: protocol.Invoke): void; - replyData(invoke: protocol.Invoke): void; - addClient(driver: WebClientDriver): void; - _Erase_user(user: User): void; + private erase_user(user); } } -declare namespace samchon.protocol.service { +declare namespace samchon.templates.service { + /** + * A service. + * + * The {@link Service} is an abstract class who represents a service, that is providing functions a specific page. + * + * Extends the {@link Service} class and defines its own service, which to be provided for the specific weg page, + * by overriding the {@link replyData replyData()} method. Note that, the service, functions for the specific page + * should be defined in this {@link Service} class, not its parent {@link Client} class who represents a remote client + * and takes communication responsibility. + * + * + * + * + * + * @handbook [Templates - Cloud Service](https://github.com/samchon/framework/wiki/TypeScript-Templates-Cloud_Service) + * @author Jeongho Nam + */ abstract class Service implements protocol.IProtocol { + /** + * @hidden + */ private client_; + /** + * @hidden + */ private path_; /** - * Default Constructor. + * Construct from parent {@link Client} and requested path. + * + * @param client Driver of remote client. + * @param path Requested path that identifies this {@link Service}. */ constructor(client: Client, path: string); - destructor(): void; + /** + * Default Destructor. + * + * This {@link destructor destructor()} method is call when the {@link Service} object is destructed and the + * {@link Service} object is destructed when its parent {@link Client} object has + * {@link Client.destructor destructed} or the {@link Client} object {@link Client.changeService changed} its + * child {@link Service service} object to another one. + * + * Note that, don't call this {@link destructor destructor()} method by yourself. It must be called automatically + * by those *destruction* cases. Also, if your derived {@link Service} class has something to do on the + * *destruction*, then overrides this {@link destructor destructor()} method and defines the something to do. + */ + protected destructor(): void; /** * Get client. */ getClient(): Client; /** - * Get path. + * Get requested path. */ getPath(): string; + /** + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message to remote system through parent {@link Client} object ({@link Client.sendData}). + * + * @param invoke An {@link Invoke} message to send to the remte system. + */ sendData(invoke: protocol.Invoke): void; - replyData(invoke: protocol.Invoke): void; + /** + * @inheritdoc + */ + abstract replyData(invoke: protocol.Invoke): void; } } -declare namespace samchon.protocol.service { - abstract class User extends collection.HashMapCollection implements protocol.IProtocol { - private server_; - private session_id_; - private sequence_; - private account_id_; - private authority_; - /** - * Construct from a Server. - */ - constructor(server: Server); - protected abstract createClient(driver: WebClientDriver): Client; +declare namespace samchon.templates.service { + /** + * An user. + * + * The {@link User} is an abstract class groupping {@link Client} objects, who communicates with remote client, with + * same *session id*. This {link User} represents a *remote user* literally. Within framework of remote system, + * an {@link User} corresponds to a web-browser and a {@link Client} represents a window in the web-browser. + * + * Extends this {@link User} class and override the {@link createClient} method, a factory method creating a child + * {@link Client} object. I repeat, the {@link User} class represents a *remote user*, groupping {@link Client} + * objects with same *session id*. If your cloud server has some processes to be handled in the **user level**, then + * defines method in this {@link User} class. Methods managing **account** under below are some of them: + * + * - {@link setAccount setAccount()} + * - {@link getAccountID getAccountID()} + * - {@link getAuthority getAuthority()} + * + * The children {@link Client} objects, they're contained with their key, the {@link Client.getNo sequence number}. + * If you {@link User.erase erase} the children {@link Client} object by yourself, then their connection with the + * remote clients will be {@link Client.close closed} and their {@link Client.destructor destruction method} will be + * called. If you remove {@link clear all children}, then this {@link User} object will be also + * {@link destructor destructed} and erased from the parent {@link Server} object. + * + * + * + * + * + * @handbook [Templates - Cloud Service](https://github.com/samchon/framework/wiki/TypeScript-Templates-Cloud_Service) + * @author Jeongho Nam + */ + abstract class User extends collections.HashMapCollection implements protocol.IProtocol { /** * @hidden */ - _Create_child(driver: WebClientDriver): Client; + private server_; + /** + * @hidden + */ + private session_id_; + /** + * @hidden + */ + private sequence_; + /** + * @hidden + */ + private account_id_; + /** + * @hidden + */ + private authority_; + /** + * Construct from its parent {@link Server}. + * + * @param server The parent {@link Server} object. + */ + constructor(server: Server); + /** + * Default Destructor. + * + * This {@link destructor destructor()} method is called when the {@link User} object is destructed. The + * {@link User} object is destructed when connections with the remote clients are all closed, that is all the + * children {@link Client} objects are all removed, and 30 seconds has left. If some remote client connects + * within the 30 seconds, then the {@link User} object doesn't be destructed. + * + * Note that, don't call this {@link destructor destructor()} method by yourself. It must be called automatically + * by those *destruction* cases. Also, if your derived {@link User} class has something to do on the + * *destruction*, then overrides this {@link destructor destructor()} method and defines the something to do. + * Overriding this {@link destructor destructor()}, don't forget to calling ```super.destructor();``` on tail. + * + * ```typescript + * class MyUser extends protocol.service.User + * { + * protected destructor(): void + * { + * // DO SOMETHING + * this.do_something(); + * + * // CALL SUPER.DESTRUCTOR() ON TAIL. DON'T FORGET THIS + * super.destructor(); + * } + * } + * ``` + */ + protected destructor(): void; + /** + * Factory method creating a {@link Client} object. + * + * @param driver A web communicator for remote client. + * @return A newly created {@link Client} object. + */ + protected abstract createClient(driver: protocol.WebClientDriver): Client; /** * @hidden */ private handle_erase_client(event); + /** + * Get parent {@lin Server} object. + * + * @return Parent {@link Server} object. + */ getServer(): Server; + /** + * Get account id. + * + * @return Account ID. + */ getAccountID(): string; + /** + * Get authority. + * + * @return Authority + */ getAuthority(): number; + /** + * Set *account id* and *authority*. + * + * The {@link setAccount setAccount()} is a method configuring *account id* and *authority* of this {@link User}. + * + * After the configuring, the {@link getAccountID account id} is enrolled into the parent {@link Server} as a + * **key** for this {@link User} object. You can test existence and access this {@link User} object from + * {@link Server.has Server.has()} and {@link Server.get Server.get()} with the {@link getAccountID account id}. + * Of course, if ordinary {@link getAccountID account id} had existed, then the ordinary **key** will be + * replaced. + * + * As you suggest, this {@link setAccount setAccount()} is something like a **log-in** function. If what you want + * is not **logging-in**, but **logging-out**, then configure the *account id* to empty string ``""```` or call + * the {@link lgout logout()} method. + * + * @param id To be account id. + * @param authority To be authority. + */ setAccount(id: string, authority: number): void; /** - * @hidden + * Log-out. + * + * This {@link logout logout()} method configures {@link getAccountID account id} to empty string and + * {@link getAuthority authority} to zero. + * + * The ordinary {@link getAccountID account id} will be also erased from the parent {@link Server} object. You + * can't access this {@link User} object from {@link Server.has Server.has()} and {@link Server.get Server.get()} + * with the ordinary {@link getAccountID account id} more. */ - _Get_session_id(): string; + logout(): void; /** - * @hidden + * Send an {@link Invoke} message. + * + * Sends an {@link Invoke} message to all remote clients through the belonged {@link Client} objects. Sending the + * {@link Invoke} message to all remote clients, it's came true by passing through the + * {@link Client.sendData Client.sendData()} methods. + * + * ```typescript + * class protocol.service.User + * { + * public sendData(invoke: Invoke): void + * { + * for (let it = this.begin(); !it.equal_to(this.end()); it = it.next()) + * it.second.sendData(invoke); + * } + * } + * ``` + * + * @param invoke {@link Invoke} message to send to all remote clients. */ - _Fetch_sequence(): number; - /** - * @hidden - */ - _Set_session_id(val: string): void; sendData(invoke: protocol.Invoke): void; + /** + * Handle a replied {@link Invoke} message. + * + * The default {@link User.replyData User.replyData()} shifts chain to its parent {@link Server} object, by + * calling the {@link Server.replyData Server.replyData()} method. If there're some {@link Invoke} message to be + * handled in this {@link User} level, then override this method and defines what to do with the {@link Invoke} + * message in this {@link User} level. + * + * ```typescript + * class protocol.service.User + * { + * public replyData(invoke: protocol.Invoke): void + * { + * this.getServer().replyData(invoke); + * } + * } + * + * class MyUser extends protocol.service.User + * { + * public replyData(invoke: protocol.Invoke): void + * { + * if (invoke.apply(this) == false) // IS TARGET TO BE HANDLED IN THIS USER LEVEL + * super.replyData(invoke); // SHIFT TO SERVER + * } + * } + * ``` + * + * @param invoke An {@link Invoke invoke} message to be handled in {@link User} level. + */ replyData(invoke: protocol.Invoke): void; } } -declare namespace samchon.protocol.slave { +declare namespace samchon.templates.slave { interface ISlaveClient extends SlaveSystem { connect(ip: string, port: number): void; } @@ -6423,25 +10275,22 @@ declare namespace samchon.protocol.slave { /** * @inheritdoc */ - protected abstract createServerConnector(): IServerConnector; + protected abstract createServerConnector(): protocol.IServerConnector; /** * @inheritdoc */ connect(ip: string, port: number): void; } } -declare namespace samchon.protocol.slave { - interface ISlaveServer extends SlaveSystem, IServer { +declare namespace samchon.templates.slave { + interface ISlaveServer extends SlaveSystem, protocol.IServer { } abstract class SlaveServer extends SlaveSystem implements ISlaveServer { private server_base_; constructor(); - protected abstract createServerBase(): IServerBase; + protected abstract createServerBase(): protocol.IServerBase; open(port: number): void; close(): void; - addClient(driver: IClientDriver): void; + addClient(driver: protocol.IClientDriver): void; } } -declare namespace samchon.test { - function test_collection(): void; -} diff --git a/typescript-stl/typescript-stl.d.ts b/typescript-stl/typescript-stl.d.ts index 35bd397459..4e4ce70e5a 100644 --- a/typescript-stl/typescript-stl.d.ts +++ b/typescript-stl/typescript-stl.d.ts @@ -1,4 +1,4 @@ -// Type definitions for TypeScript-STL v1.1.0 +// Type definitions for TypeScript-STL v1.1.2 // Project: https://github.com/samchon/typescript-stl // Definitions by: Jeongho Nam // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -22,93 +22,6 @@ declare module "typescript-stl" * @author Jeongho Nam */ declare namespace std { - /** - * Type definition of {@link Vector} and it's the original name used in C++. - */ - export import vector = Vector; - /** - * Type definition of {@link List} and it's the original name used in C++. - */ - export import list = List; - /** - * Type definition of {@link Deque} and it's the original name used in C++. - */ - export import deque = Deque; - /** - * Type definition of {@link Stack} and it's the original name used in C++. - */ - type stack = Stack; - /** - * Type definition of {@link Queue} and it's the original name used in C++. - */ - type queue = Queue; - /** - * Type definition of {@link PriorityQueue} and it's the original name used in C++. - */ - type priority_queue = PriorityQueue; - var stack: typeof Stack; - var queue: typeof Queue; - var priority_queue: typeof PriorityQueue; - /** - * Type definition of {@link TreeSet} and it's the original name used in C++. - */ - export import set = TreeSet; - /** - * Type definition of {@link TreeMultiSet} and it's the original name used in C++. - */ - export import multiset = TreeMultiSet; - /** - * Type definition of {@link HashSet} and it's the original name used in C++. - */ - export import unordered_set = HashSet; - /** - * Type definition of {@link HashMultiSet} and it's the original name used in C++. - */ - export import unordered_multiset = HashMultiSet; - /** - * Type definition of {@link TreeMap} and it's the original name used in C++. - */ - export import map = TreeMap; - /** - * Type definition of {@link TreeMultiMap} and it's the original name used in C++. - */ - export import multimap = TreeMultiMap; - /** - * Type definition of {@link HashMap} and it's the original name used in C++. - */ - export import unordered_map = HashMap; - /** - * Type definition of {@link HashMultiMap} and it's the original name used in C++. - */ - export import unordered_multimap = HashMultiMap; - type exception = Exception; - type logic_error = LogicError; - type domain_error = DomainError; - type invalid_argument = InvalidArgument; - type length_error = LengthError; - type out_of_range = OutOfRange; - type runtime_error = RuntimeError; - type overflow_error = OverflowError; - type underflow_error = UnderflowError; - type range_error = RangeError; - type system_error = SystemError; - type error_category = ErrorCategory; - type error_condition = ErrorCondition; - type error_code = ErrorCode; - var exception: typeof Exception; - var logic_error: typeof LogicError; - var domain_error: typeof DomainError; - var invalid_argument: typeof InvalidArgument; - var length_error: typeof LengthError; - var out_of_range: typeof OutOfRange; - var runtime_error: typeof RuntimeError; - var overflow_error: typeof OverflowError; - var underflow_error: typeof UnderflowError; - var range_error: typeof RangeError; - var system_error: typeof SystemError; - var error_category: typeof ErrorCategory; - var error_condition: typeof ErrorCondition; - var error_code: typeof ErrorCode; } /** * Base classes composing STL in background. @@ -738,7 +651,7 @@ declare namespace std { * * @return An iterator to the end of the destination range where elements have been copied. */ - function copy, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator): OutputIterator; + function copy, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator): OutputIterator; /** *

        Copy elements.

        * @@ -762,7 +675,7 @@ declare namespace std { * * @return An iterator to the end of the destination range where elements have been copied. */ - function copy_n, OutputIterator extends Iterator>(first: InputIterator, n: number, result: OutputIterator): OutputIterator; + function copy_n, OutputIterator extends base.ILinearIterator>(first: InputIterator, n: number, result: OutputIterator): OutputIterator; /** *

        Copy certain elements of range.

        * @@ -781,7 +694,7 @@ declare namespace std { * * @return An iterator to the end of the destination range where elements have been copied. */ - function copy_if, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (x: T) => boolean): OutputIterator; + function copy_if, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (x: T) => boolean): OutputIterator; /** *

        Copy range of elements backward.

        * @@ -808,7 +721,7 @@ declare namespace std { * * @return An iterator to the first element of the destination sequence where elements have been copied. */ - function copy_backward, BidirectionalIterator2 extends Iterator>(first: BidirectionalIterator1, last: BidirectionalIterator1, result: BidirectionalIterator2): BidirectionalIterator2; + function copy_backward, BidirectionalIterator2 extends base.ILinearIterator>(first: BidirectionalIterator1, last: BidirectionalIterator1, result: BidirectionalIterator2): BidirectionalIterator2; /** *

        Fill range with value.

        * @@ -822,7 +735,7 @@ declare namespace std { * but not the element pointed by last. * @param val Value to assign to the elements in the filled range. */ - function fill>(first: ForwardIterator, last: ForwardIterator, val: T): void; + function fill>(first: ForwardIterator, last: ForwardIterator, val: T): void; /** *

        Fill sequence with value.

        * @@ -835,7 +748,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element filled. */ - function fill_n>(first: OutputIterator, n: number, val: T): OutputIterator; + function fill_n>(first: OutputIterator, n: number, val: T): OutputIterator; /** *

        Transform range.

        * @@ -853,7 +766,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element written in the result sequence. */ - function transform, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, op: (val: T) => T): OutputIterator; + function transform, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, op: (val: T) => T): OutputIterator; /** *

        Transform range.

        * @@ -874,7 +787,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element written in the result sequence. */ - function transform, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, result: OutputIterator, binary_op: (x: T, y: T) => T): OutputIterator; + function transform, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, result: OutputIterator, binary_op: (x: T, y: T) => T): OutputIterator; /** *

        Generate values for range with function.

        * @@ -888,7 +801,7 @@ declare namespace std { * @param gen Generator function that is called with no arguments and returns some value of a type convertible to * those pointed by the iterators. */ - function generate>(first: ForwardIterator, last: ForwardIterator, gen: () => T): void; + function generate>(first: ForwardIterator, last: ForwardIterator, gen: () => T): void; /** *

        Generate values for sequence with function.

        * @@ -903,7 +816,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element whose value has been generated. */ - function generate_n>(first: ForwardIterator, n: number, gen: () => T): ForwardIterator; + function generate_n>(first: ForwardIterator, n: number, gen: () => T): ForwardIterator; /** *

        Remove consecutive duplicates in range.

        * @@ -975,7 +888,7 @@ declare namespace std { * * @return An iterator pointing to the end of the copied range, which contains no consecutive duplicates. */ - function unique_copy, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator): OutputIterator; + function unique_copy, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator): OutputIterator; /** *

        Copy range removing duplicates.

        * @@ -1001,7 +914,7 @@ declare namespace std { * * @return An iterator pointing to the end of the copied range, which contains no consecutive duplicates. */ - function unique_copy, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (x: T, y: T) => boolean): OutputIterator; + function unique_copy, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (x: T, y: T) => boolean): OutputIterator; /** *

        Remove value from range.

        * @@ -1069,7 +982,7 @@ declare namespace std { * @return An iterator pointing to the end of the copied range, which includes all the elements in * [first, last) except those that compare equal to val. */ - function remove_copy, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, val: T): OutputIterator; + function remove_copy, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, val: T): OutputIterator; /** *

        Copy range removing values.

        * @@ -1093,7 +1006,7 @@ declare namespace std { * @return An iterator pointing to the end of the copied range, which includes all the elements in * [first, last) except those for which pred returns true. */ - function remove_copy_if, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (val: T) => boolean): OutputIterator; + function remove_copy_if, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (val: T) => boolean): OutputIterator; /** *

        Replace value in range.

        * @@ -1109,7 +1022,7 @@ declare namespace std { * @param old_val Value to be replaced. * @param new_val Replacement value. */ - function replace>(first: InputIterator, last: InputIterator, old_val: T, new_val: T): void; + function replace>(first: InputIterator, last: InputIterator, old_val: T, new_val: T): void; /** *

        Replace value in range.

        * @@ -1125,7 +1038,7 @@ declare namespace std { * true, it is replaced). The function shall not modify its argument. * @param new_val Value to assign to replaced elements. */ - function replace_if>(first: InputIterator, last: InputIterator, pred: (val: T) => boolean, new_val: T): void; + function replace_if>(first: InputIterator, last: InputIterator, pred: (val: T) => boolean, new_val: T): void; /** *

        Copy range replacing value.

        * @@ -1149,7 +1062,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element written in the result sequence. */ - function replace_copy, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, old_val: T, new_val: T): OutputIterator; + function replace_copy, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, old_val: T, new_val: T): OutputIterator; /** *

        Copy range replacing value.

        * @@ -1170,7 +1083,7 @@ declare namespace std { * * @return An iterator pointing to the element that follows the last element written in the result sequence. */ - function replace_copy_if, OutputIterator extends Iterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (val: T) => boolean, new_val: T): OutputIterator; + function replace_copy_if, OutputIterator extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result: OutputIterator, pred: (val: T) => boolean, new_val: T): OutputIterator; /** *

        Exchange values of objects pointed to by two iterators.

        * @@ -1230,7 +1143,7 @@ declare namespace std { * @return An output iterator pointing to the end of the copied range, which contains the same elements in reverse * order. */ - function reverse_copy, OutputIterator extends Iterator>(first: BidirectionalIterator, last: BidirectionalIterator, result: OutputIterator): OutputIterator; + function reverse_copy, OutputIterator extends base.ILinearIterator>(first: BidirectionalIterator, last: BidirectionalIterator, result: OutputIterator): OutputIterator; /** *

        Rotate left the elements in range.

        * @@ -1266,7 +1179,7 @@ declare namespace std { * * @return An output iterator pointing to the end of the copied range. */ - function rotate_copy, OutputIterator extends Iterator>(first: ForwardIterator, middle: ForwardIterator, last: ForwardIterator, result: OutputIterator): OutputIterator; + function rotate_copy, OutputIterator extends base.ILinearIterator>(first: ForwardIterator, middle: ForwardIterator, last: ForwardIterator, result: OutputIterator): OutputIterator; /** *

        Randomly rearrange elements in range.

        * @@ -2147,7 +2060,7 @@ declare namespace std { * member {@link Pair.second second} points to the element that follows the last element copied to the sequence * of elements for which pred returned false. */ - function partition_copy, OutputIterator1 extends Iterator, OutputIterator2 extends Iterator>(first: InputIterator, last: InputIterator, result_true: OutputIterator1, result_false: OutputIterator2, pred: (val: T) => T): Pair; + function partition_copy, OutputIterator1 extends base.ILinearIterator, OutputIterator2 extends base.ILinearIterator>(first: InputIterator, last: InputIterator, result_true: OutputIterator1, result_false: OutputIterator2, pred: (val: T) => T): Pair; /** *

        Get partition point.

        * @@ -2196,7 +2109,7 @@ declare namespace std { * * @return An iterator pointing to the past-the-end element in the resulting sequence. */ - function merge, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; + function merge, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; /** *

        Merge sorted ranges.

        * @@ -2222,7 +2135,7 @@ declare namespace std { * * @return An iterator pointing to the past-the-end element in the resulting sequence. */ - function merge, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; + function merge, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; /** *

        Merge consecutive sorted ranges.

        * @@ -2353,7 +2266,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_union, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; + function set_union, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; /** *

        Union of two sorted ranges.

        * @@ -2386,7 +2299,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_union, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; + function set_union, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; /** *

        Intersection of two sorted ranges.

        * @@ -2414,7 +2327,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_intersection, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; + function set_intersection, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; /** *

        Intersection of two sorted ranges.

        * @@ -2446,7 +2359,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_intersection, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; + function set_intersection, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; /** *

        Difference of two sorted ranges.

        * @@ -2480,7 +2393,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_difference, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; + function set_difference, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; /** *

        Difference of two sorted ranges.

        * @@ -2518,7 +2431,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_difference, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; + function set_difference, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; /** *

        Symmetric difference of two sorted ranges.

        * @@ -2552,7 +2465,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_symmetric_difference, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; + function set_symmetric_difference, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator): OutputIterator; /** *

        Symmetric difference of two sorted ranges.

        * @@ -2586,7 +2499,7 @@ declare namespace std { * * @return An iterator to the end of the constructed range. */ - function set_symmetric_difference, InputIterator2 extends Iterator, OutputIterator extends Iterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; + function set_symmetric_difference, InputIterator2 extends Iterator, OutputIterator extends base.ILinearIterator>(first1: InputIterator1, last1: InputIterator1, first2: InputIterator2, last2: InputIterator2, result: OutputIterator, compare: (x: T, y: T) => boolean): OutputIterator; } declare namespace std { /** @@ -2844,7 +2757,7 @@ declare namespace std.base { /** * @inheritdoc */ - abstract push(...items: U[]): number; + abstract push(...items: T[]): number; /** * @inheritdoc */ @@ -4594,11 +4507,11 @@ declare namespace std.base { /** * @inheritdoc */ - push(...args: Pair[]): number; + push(...args: Pair[]): number; /** * @inheritdoc */ - push(...args: [Key, T][]): number; + push(...args: [Key, T][]): number; /** * Construct and insert element with hint * @@ -4842,6 +4755,18 @@ declare namespace std.base { * @hidden */ private erase_by_range(begin, end); + /** + * @hidden + */ + protected _Swap(obj: MapContainer): void; + /** + * Merge two maps. + * + * Extracts and transfers elements from *source* to this container. + * + * @param source A {@link MapContainer map container} to transfer the elements from. + */ + abstract merge(source: MapContainer): void; /** *

        Abstract method handling insertions for indexing.

        * @@ -4885,10 +4810,6 @@ declare namespace std.base { * including the element pointed by first but not the element pointed by last. */ protected abstract _Handle_erase(first: MapIterator, last: MapIterator): void; - /** - * @hidden - */ - protected _Swap(obj: MapContainer): void; } } declare namespace std { @@ -5067,50 +4988,6 @@ declare namespace std.base { * @param val Value, the item. */ set(key: Key, val: T): void; - /** - *

        Extract an element.

        - * - *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        - * - * @param key Key value of the element whose mapped value is accessed. - * - * @return A {@link Pair} containing the value pointed to by key. - */ - extract(key: Key): Pair; - /** - *

        Extract an element.

        - * - *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        - * - * @param it An iterator pointing an element to extract. - * - * @return An iterator pointing to the element immediately following it prior to the element being - * erased. If no such element exists,returns {@link end end()}. - */ - extract(it: MapIterator): MapIterator; - /** - *

        Extract an element.

        - * - *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        - * - * @param it An iterator pointing an element to extract. - * - * @return An iterator pointing to the element immediately following it prior to the element being - * erased. If no such element exists,returns {@link end end()}. - */ - extract(it: MapReverseIterator): MapReverseIterator; - /** - * @hidden - */ - private extract_by_key(key); - /** - * @hidden - */ - private extract_by_iterator(it); - /** - * @hidden - */ - private extract_by_reverse_iterator(it); /** * Construct and insert element. * @@ -5293,6 +5170,61 @@ declare namespace std.base { * @hidden */ private insert_or_assign_with_hint(hint, key, value); + /** + *

        Extract an element.

        + * + *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        + * + * @param key Key value of the element whose mapped value is accessed. + * + * @return A {@link Pair} containing the value pointed to by key. + */ + extract(key: Key): Pair; + /** + *

        Extract an element.

        + * + *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        + * + * @param it An iterator pointing an element to extract. + * + * @return An iterator pointing to the element immediately following it prior to the element being + * erased. If no such element exists,returns {@link end end()}. + */ + extract(it: MapIterator): MapIterator; + /** + *

        Extract an element.

        + * + *

        Extracts the element pointed to by key and erases it from the {@link UniqueMap}.

        + * + * @param it An iterator pointing an element to extract. + * + * @return An iterator pointing to the element immediately following it prior to the element being + * erased. If no such element exists,returns {@link end end()}. + */ + extract(it: MapReverseIterator): MapReverseIterator; + /** + * @hidden + */ + private extract_by_key(key); + /** + * @hidden + */ + private extract_by_iterator(it); + /** + * @hidden + */ + private extract_by_reverse_iterator(it); + /** + * Merge two maps. + * + * Attempts to extract each element in *source* and insert it into this container. If there's an element in this + * container with key equivalent to the key of an element from *source*, tnen that element is not extracted from + * the *source*. Otherwise, no element with same key exists in this container, then that element will be + * transfered from the *source* to this container. + * + * @param source A {@link MapContainer map container} to transfer the elements from. + */ + merge(source: MapContainer): void; } } declare namespace std.base { @@ -5419,6 +5351,10 @@ declare namespace std.base { * @inheritdoc */ insert>>(first: InputIterator, last: InputIterator): void; + /** + * @inheritdoc + */ + merge(source: MapContainer): void; } } declare namespace std.HashMap { @@ -5638,8 +5574,8 @@ declare namespace std { *

        Elements with equivalent keys are grouped together in the same bucket and in such a way that * an iterator can iterate through all of them. Iterators in the container are doubly linked iterators.

        * - *

        - * + *

        + * *

        * *

        Container properties

        @@ -5926,7 +5862,7 @@ declare namespace std.base { /** * @inheritdoc */ - push(...args: U[]): number; + push(...args: T[]): number; /** *

        Insert an element with hint.

        * @@ -6026,6 +5962,18 @@ declare namespace std.base { * @hidden */ private erase_by_range(begin, end); + /** + * @hidden + */ + protected _Swap(obj: SetContainer): void; + /** + * Merge two sets. + * + * Extracts and transfers elements from *source* to this container. + * + * @param source A {@link SetContainer set container} to transfer the elements from. + */ + abstract merge(source: SetContainer): void; /** *

        Abstract method handling insertions for indexing.

        * @@ -6069,10 +6017,6 @@ declare namespace std.base { * including the element pointed by first but not the element pointed by last. */ protected abstract _Handle_erase(first: SetIterator, last: SetIterator): void; - /** - * @hidden - */ - protected _Swap(obj: SetContainer): void; } } declare namespace std { @@ -6220,6 +6164,10 @@ declare namespace std.base { * @inheritdoc */ insert>(begin: InputIterator, end: InputIterator): void; + /** + * @inheritdoc + */ + merge(source: SetContainer): void; } } declare namespace std.HashMultiSet { @@ -6451,6 +6399,38 @@ declare namespace std.base { * @inheritdoc */ count(key: T): number; + /** + *

        Insert an element.

        + * + *

        Extends the container by inserting new elements, effectively increasing the container {@link size} by + * the number of element inserted (zero or one).

        + * + *

        Because elements in a {@link UniqueSet UniqueSets} are unique, the insertion operation checks whether + * each inserted element is equivalent to an element already in the container, and if so, the element is not + * inserted, returning an iterator to this existing element (if the function returns a value).

        + * + *

        For a similar container allowing for duplicate elements, see {@link MultiSet}.

        + * + * @param key Value to be inserted as an element. + * + * @return A {@link Pair}, with its member {@link Pair.first} set to an iterator pointing to either the newly + * inserted element or to the equivalent element already in the {@link UniqueSet}. The + * {@link Pair.second} element in the {@link Pair} is set to true if a new element was inserted or + * false if an equivalent element already existed. + */ + insert(val: T): Pair, boolean>; + /** + * @inheritdoc + */ + insert(hint: SetIterator, val: T): SetIterator; + /** + * @inheritdoc + */ + insert(hint: SetReverseIterator, val: T): SetReverseIterator; + /** + * @inheritdoc + */ + insert>(begin: InputIterator, end: InputIterator): void; /** *

        Extract an element.

        * @@ -6496,37 +6476,16 @@ declare namespace std.base { */ private extract_by_reverse_iterator(it); /** - *

        Insert an element.

        + * Merge two sets. * - *

        Extends the container by inserting new elements, effectively increasing the container {@link size} by - * the number of element inserted (zero or one).

        + * Attempts to extract each element in *source* and insert it into this container. If there's an element in this + * container with key equivalent to the key of an element from *source*, tnen that element is not extracted from + * the *source*. Otherwise, no element with same key exists in this container, then that element will be + * transfered from the *source* to this container. * - *

        Because elements in a {@link UniqueSet UniqueSets} are unique, the insertion operation checks whether - * each inserted element is equivalent to an element already in the container, and if so, the element is not - * inserted, returning an iterator to this existing element (if the function returns a value).

        - * - *

        For a similar container allowing for duplicate elements, see {@link MultiSet}.

        - * - * @param key Value to be inserted as an element. - * - * @return A {@link Pair}, with its member {@link Pair.first} set to an iterator pointing to either the newly - * inserted element or to the equivalent element already in the {@link UniqueSet}. The - * {@link Pair.second} element in the {@link Pair} is set to true if a new element was inserted or - * false if an equivalent element already existed. + * @param source A {@link SetContainer set container} to transfer the elements from. */ - insert(val: T): Pair, boolean>; - /** - * @inheritdoc - */ - insert(hint: SetIterator, val: T): SetIterator; - /** - * @inheritdoc - */ - insert(hint: SetReverseIterator, val: T): SetReverseIterator; - /** - * @inheritdoc - */ - insert>(begin: InputIterator, end: InputIterator): void; + merge(source: SetContainer): void; } } declare namespace std.HashSet { @@ -6859,7 +6818,7 @@ declare namespace std { /** * @inheritdoc */ - push(...items: U[]): number; + push(...items: T[]): number; /** * @inheritdoc */ @@ -7410,7 +7369,7 @@ declare namespace std { * * @author Jeongho Nam */ - class ListReverseIterator extends ReverseIterator, ListReverseIterator> { + class ListReverseIterator extends ReverseIterator, ListReverseIterator> implements base.ILinearIterator { /** * Construct from base iterator. * @@ -8664,7 +8623,7 @@ declare namespace std { *

        In a {@link TreeMultiSet}, the value of an element also identifies it (the value is itself * the key, of type T). The value of the elements in a {@link TreeMultiSet} cannot * be modified once in the container (the elements are always const), but they can be inserted or removed - * from the

        + * from the container.

        * *

        Internally, the elements in a {@link TreeMultiSet TreeMultiSets} are always sorted following a strict * weak ordering criterion indicated by its internal comparison method (of {@link IComparable.less less}).

        @@ -8848,7 +8807,7 @@ declare namespace std { *

        In a {@link TreeSet}, the value of an element also identifies it (the value is itself the * key, of type T), and each value must be unique. The value of the elements in a * {@link TreeSet} cannot be modified once in the container (the elements are always const), but they - * can be inserted or removed from the

        + * can be inserted or removed from the container.

        * *

        Internally, the elements in a {@link TreeSet} are always sorted following a specific strict weak * ordering criterion indicated by its internal comparison method (of {@link less}).

        @@ -9096,12 +9055,12 @@ declare namespace std { *

        Just like arrays, {@link Vector}s use contiguous storage locations for their elements, which means that * their elements can also be accessed using offsets on regular pointers to its elements, and just as efficiently * as in arrays. But unlike arrays, their size can change dynamically, with their storage being handled - * automatically by the

        + * automatically by the container.

        * *

        Internally, {@link Vector}s use a dynamically allocated array to store their elements. This array may need * to be reallocated in order to grow in size when new elements are inserted, which implies allocating a new * array and moving all elements to it. This is a relatively expensive task in terms of processing time, and - * thus, {@link Vector}s do not reallocate each time an element is added to the

        + * thus, {@link Vector}s do not reallocate each time an element is added to the container.

        * *

        Instead, {@link Vector} containers may allocate some extra storage to accommodate for possible growth, and * thus the container may have an actual {@link capacity} greater than the storage strictly needed to contain its @@ -9508,7 +9467,7 @@ declare namespace std { * with the same template parameter, T) whose content is swapped with that of this * {@link container Vector}. */ - obj(obj: Vector): void; + swap(obj: Vector): void; /** * @inheritdoc */ @@ -10429,8 +10388,6 @@ declare namespace std.base { */ set(index: number, val: T): void; } -} -declare namespace std.base { /** *

        Random-access iterator.

        * @@ -10451,7 +10408,7 @@ declare namespace std.base { * @reference http://www.cplusplus.com/reference/iterator/RandomAccessIterator * @author Jeongho Nam */ - interface IArrayIterator extends Iterator { + interface IArrayIterator extends ILinearIterator { /** * Get index, sequence number of the iterator in the source {@link IArray array}. * @@ -10596,7 +10553,7 @@ declare namespace std.base { * * @return New size of the Container. */ - push(...items: U[]): number; + push(...items: T[]): number; /** *

        Insert an element.

        * @@ -10807,6 +10764,29 @@ declare namespace std.base { */ insert>(position: Iterator, begin: InputIterator, end: InputIterator): Iterator; } + /** + * An interface for iterators from linear containers. + * + * {@link ILieanerIterator} is an bi-directional iterator which is created from the related + * {@link ILinearContainer linear containers}. Not only accessing to {@link value} of the pointed element from + * this {@link ILieanerIterator}, but also modifying the {@link value} is possible. + * + * @author Jeongho Nam + */ + interface ILinearIterator extends Iterator { + /** + * @inheritdoc + */ + value: T; + /** + * @inheritdoc + */ + prev(): ILinearIterator; + /** + * @inheritdoc + */ + next(): ILinearIterator; + } } declare namespace std.base { /** @@ -12087,3 +12067,92 @@ declare namespace std.base { uncle: XTreeNode; } } +declare namespace std { + /** + * Type definition of {@link Vector} and it's the original name used in C++. + */ + export import vector = Vector; + /** + * Type definition of {@link List} and it's the original name used in C++. + */ + export import list = List; + /** + * Type definition of {@link Deque} and it's the original name used in C++. + */ + export import deque = Deque; + /** + * Type definition of {@link Stack} and it's the original name used in C++. + */ + type stack = Stack; + /** + * Type definition of {@link Queue} and it's the original name used in C++. + */ + type queue = Queue; + /** + * Type definition of {@link PriorityQueue} and it's the original name used in C++. + */ + type priority_queue = PriorityQueue; + var stack: typeof Stack; + var queue: typeof Queue; + var priority_queue: typeof PriorityQueue; + /** + * Type definition of {@link TreeSet} and it's the original name used in C++. + */ + export import set = TreeSet; + /** + * Type definition of {@link TreeMultiSet} and it's the original name used in C++. + */ + export import multiset = TreeMultiSet; + /** + * Type definition of {@link HashSet} and it's the original name used in C++. + */ + export import unordered_set = HashSet; + /** + * Type definition of {@link HashMultiSet} and it's the original name used in C++. + */ + export import unordered_multiset = HashMultiSet; + /** + * Type definition of {@link TreeMap} and it's the original name used in C++. + */ + export import map = TreeMap; + /** + * Type definition of {@link TreeMultiMap} and it's the original name used in C++. + */ + export import multimap = TreeMultiMap; + /** + * Type definition of {@link HashMap} and it's the original name used in C++. + */ + export import unordered_map = HashMap; + /** + * Type definition of {@link HashMultiMap} and it's the original name used in C++. + */ + export import unordered_multimap = HashMultiMap; + type exception = Exception; + type logic_error = LogicError; + type domain_error = DomainError; + type invalid_argument = InvalidArgument; + type length_error = LengthError; + type out_of_range = OutOfRange; + type runtime_error = RuntimeError; + type overflow_error = OverflowError; + type underflow_error = UnderflowError; + type range_error = RangeError; + type system_error = SystemError; + type error_category = ErrorCategory; + type error_condition = ErrorCondition; + type error_code = ErrorCode; + var exception: typeof Exception; + var logic_error: typeof LogicError; + var domain_error: typeof DomainError; + var invalid_argument: typeof InvalidArgument; + var length_error: typeof LengthError; + var out_of_range: typeof OutOfRange; + var runtime_error: typeof RuntimeError; + var overflow_error: typeof OverflowError; + var underflow_error: typeof UnderflowError; + var range_error: typeof RangeError; + var system_error: typeof SystemError; + var error_category: typeof ErrorCategory; + var error_condition: typeof ErrorCondition; + var error_code: typeof ErrorCode; +}