Objects
and
Types |
Name |
Methods |
Generated By |
Description |
Max Num |
| EventMarshaller |
postEvent
unpostEvent
dispatch
getEventMax
setEventMax
getEventTotal
|
createEventMarshaller |
An EventMarshaller is a
prioritised-queuing mechanism, to which the application posts 'events'. For each posting, the marshaller
adds a reference to a user-supplied function to its queue. That function constitutes a 'response' to the
posted event.
Applications post events until a user-defined maximum is reached, whereupon the marshaller 'dispatches'
its queue by removing each response-function reference in turn from the queue before invoking it.
An EventMarshaller with a queue threshold of 1 will simply
dispatch each event's response as the event is posted.
Response functions are dispatched according to the priority that the
application may have given them at the time of posting, such that those with higher priorities are dispatched
before those with lower ones. Where no responses have a priority, the marshaller in question
operates purely as a FIFO queue. Where two or more responses have the
same priority, they are dispatched in the order in which they
were posted.
Response priorities can have negative or positive values of any
magnitude, including Infinity.
Once dispatched from their respective queues, Response objects are
useless from the point of view of event marshalling.
|
unlimited |
| Response |
-
|
EventMarshaller |
A Response object represents a queued response to an event that has been posted to
an EventMarshaller. It has no attributes or methods and is returned to client code purely to
enable a given event to be unposted subsequently should the need arise.
|
unlimited |
| Global |
createEventMarshaller
EventMarshaller_DbC
|
Platform |
-
|
1 |
|
| Methods |
Name |
Owner |
Returns |
Description |
| createEventMarshaller |
Global |
EventMarshaller |
Generates and returns EventMarshaller objects.
|
|
| postEvent |
EventMarshaller |
Response |
Causes a response function that corresponds to the event to be
added to a marshaller's queue.
Calling postEvent on a marshaller that is dispatching
its queue has no effect.
|
|
| unpostEvent |
EventMarshaller |
See Note 1 |
Removes a response function from a marshaller's queue.
following which it has no significance in terms of event
marshalling.
|
|
| getEventMax |
EventMarshaller |
number |
Returns the maximum queue-size for an EventMarshaller.
|
|
| setEventMax |
EventMarshaller |
number |
Sets the maximum queue-size for an EventMarshaller.
If the value for NewEventMax is equal to or less than the
current number of responses in the queue then the marshaller
will dispatch the queue automatically.
Setting an EventMarshaller's event maximum whilst it is
dispatching its queue (e.g. from within a response function that
has been invoked in the process of dispatching that queue) has
no effect on the current queue-dispatch. It does, however, set
the maximum for the next queue to be formed through that
marshaller.
|
|
| getEventTotal |
EventMarshaller |
number |
Returns the total number of events that have been posted to
the marshaller in question.
|
|
| dispatch |
EventMarshaller |
|
Forces an EventMarshaller to dispatch the responses in its
queue, irrespective of the queue's size.
Calling dispatch on a marshaller that is dispatching its queue
has no effect.
|
|
| ResponseFunc |
* |
* |
Performs a user-defined task that corresponds to the posting of
an event to an EventMarshaller. A response function is called by
an EventMarshaller just once, and only when the marshaller
dispatches its queue.
Returning something from a response function is redundant as any
value/object returned is ignored by the corresponding
EventMarshaller when it dispatches its queue.
Should a response function throw an exception upon invocation
dispatch of that marshaller's queue will halt, leaving any
un-dispatched responses in the queue. However, this
does not corrupt the marshaller in
question, and the object will continue to operate normally thereafter.
|
|
| eventMarshaller_DbC |
Global |
undefined |
Uses the AspectJS AJS-object to apply a prefix to createEventMarshaller, such that
the passing of bad parameters to that function generates an exception.
The prefix also applies a
suffix to createEventMarshaller that applies further affixes
to the methods of any EventMarshaller objects created.
Those affixes also raise an exception when bad or missing parameters
are passed to those methods.
Any application that uses eventMarshaller_DbC must import an instance of
the AJS-object.
|
|
|
| Signatures | Returns | Owner | Function | Arguments... |
| EventMarshaller | Global | createEventMarshaller | ( | EventMax | | | | | [, | CallPoint]) | |
| Response | EventMarshaller | postEvent | ( | ResponseFunc | [, | Arg | [, | Priority | [, | CallPoint]]]) | |
| Response | EventMarshaller | unpostEvent | ( | Response | | | | | [, | CallPoint]) | |
| number | EventMarshaller | getEventMax | ( | | | | | | [ | CallPoint]) | |
| number | EventMarshaller | setEventMax | ( | NewEventMax | | | | | [, | CallPoint]) | |
| number | EventMarshaller | getEventTotal | ( | | | | | | [ | CallPoint]) | |
| undefined | EventMarshaller | dispatch | ( | | | | | | [ | CallPoint]) | |
| * | * | ResponseFunc | ([ | Arg | [, | Priority | | | [, | CallPoint]]]) | |
| undefined | Global | eventMarshaller_DbC | ( | CEMOwner | , | CEMName | , | AJS | [, | CallPoint]) | |
|
| Arguments | Name | Type | Denotes | Optional | Default Value | Can be
Null | Can be < 1 |
| EventMax | number | A marshaller's queue-size | No | - | - | No |
| NewEventMax | number | New value for a marshaller's queue-size | No | - | - | No |
| ResponseFunc | function | Function to execute on response-dispatch | No | - | No | - |
| Response | Response | A Response object | No | - | No | - |
| Arg | * | Argument passed to response function on execution | Yes | undefined | Yes | Yes |
| Priority | number | An event's priority | Yes | 0 | No | Yes |
| CEMOwner | Object | Reference to createEventMarshaller's owner | No | - | No | - |
| CEMName | string | Name of createEventMarshaller function | No | - | No | - |
| AJS | AJS object | The AspectJS AJS-object | No | - | No | - |
| CallPoint | string | User-defined profiling/debugging data | Yes | undefined | Yes | Yes |
|
| Returns | Function | Type | Denotes | Caller
Should
Retain | Can be
Calling-Object | Can
be
Null | Can be < 1 |
| createEventMarshaller | EventMarshaller | A new EventMarshaller object | Yes | No | No | - |
| postEvent | Response | A new Response object | User Decides | No | No | - |
| unpostEvent | Response | The un-posted Response object, or the object passed | User Decides | No | Yes | No |
| getEventMax | number | Maximum number of events a marshaller will accept | User Decides | No | No | No |
| setEventMax | number | Old event-maximum a marshaller accepted | User Decides | No | No | No |
| getEventTotal | number | Total number of responses a marshaller holds currently | User Decides | No | No | No |
| dispatch | undefined | - | - | - | - | - |
| ResponseFunc | * | * | User Decides | No | Yes | User Decides |
| eventMarshaller_DbC | undefined | - | - | - | - | - |
|
| Exceptions |
Function |
Throw(s) Error Object if... |
Provisos |
| createEventMarshaller |
EventMax is undefined
EventMax is null
EventMax is non-numeric
EventMax is less than 1
EventMax is Infinity
EventMax argument has a non-integer value
|
Applies only if you
import and call
eventMarshaller_DbC
into and within
your application.
|
| postEvent |
ResponseFunc is undefined
ResponseFunc is null
ResponseFunc does not refer to a function
Priority is null
Priority is non-numeric
|
Applies only if you
import and call
eventMarshaller_DbC
into and within
your application.
|
| unpostEvent |
Response argument is undefined
Response argument is null
Response argument does not refer to an object
Response argument does not refer to a Response object
Response argument does not refer to an object in the marshaller's queue
|
Applies only if you
import and call
eventMarshaller_DbC
into and within
your application.
|
| setEventMax |
NewEventMax argument is undefined
NewEventMax argument is null
NewEventMax argument is non-numeric
NewEventMax argument is less than 1
NewEventMax argument is Infinity
NewEventMax argument has a non-integer value
|
Applies only if you
import and call
eventMarshaller_DbC
into and within
your application.
|
getEventMax
getEventTotal
dispatch
|
-
|
|
ResponseFunc
|
User Decides
|
|
eventMarshaller_DbC
|
CEMOwner argument is undefined
CEMOwner argument is null
CEMOwner argument does not refer to an object
CEMName argument is undefined
CEMName argument is null
CEMName argument is not a string
function denoted by CEMName argument is not a member of CEMOwner object
AJS argument is undefined
AJS argument does not refer to an object
Object referred to by AJS argument has no getVersion method
AJS argument does not refer to version 1.1 of the AJS object
Repeated call to eventMarshaller_DbC
|
Applies only if you
import and call
eventMarshaller_DbC
into and within
your application.
|
