public interface EventDatagram extends ImmutableEventDatagram, EventDatagramWithProperties
Title: Structured Data Objects
Description: A general interface for all event datagram types.
An Event Datagram
is analogous to a message. It represents the most basic unit of information exchange
between Service Event Fabric
components. Clients and components alike use events to exchange data,
state advisories and delta images that represent state changes. The Event Datagram
is a
parent interface for several critical event prototypes:
Event Datagram
extends the ImmutableEventDatagram
interface which is the prototype for the
basic state notification event:
Users may define their own event types by extending the prototype datagrams. However all events share similar characteristics and methods inherited from this basic immutable interface. All event datagrams support a common set of event properties:
eventSource
- The fabric address of the component that generated the event. Set by the dispatcher.serialVersionUID
- The serial version unique identifier for this object. Hardcoded at object definition.eventId
- The event identifier (and Subject) that identifies this event type.eventKey
- A key that uniquely identifies this event instance.eventGroupId
- An identifier that may be used to group or sequence events.correlationId
- An identifier that may be used to correlate this event to another event or key.eventReplyTo
- An event identifier (and Subject) that may be used to raise a reply event.eventForwardTo
- An event identifier (and Subject) that may be used to forward an event.durable
- A flag that indicates whether the event is durable. Durable is a hint to persist or cache events.timeStamp
- The time stamp of when the event was raised to the dispatcher. Set by the dispatcher.principal
- The name of the user (principal) that was used to protect this event datagram.credential
- The credential (security key or password) that was used to protect this event datagram.Access Control
- The access control object used to protect this event datagram. See AccessControl
ImmutableEventDatagram
and are static, meaning that users may not set additional properties on the datagrams or the
event identity management and routing properties:
eventId
eventKey
eventGroupId
correlationId
eventReplyTo
eventForwardTo
Data Event
and the Delta Event
datagrams implement the EventDatagram
interface which
adds methods for setting all critical Event Identity Management
and Datagram Header
properties. User
defined datagram properties may also be set. This information along with annotations allows the datagram to be efficiently
routed and filtered by the messaging services of the fabric. Event Identity Management
fields may also be
used to uniquely identify the eventgram object within a group, sequence or a message exchange operation.
In general, events are strong-typed, meaning that an eventId
uniquely identifies an event with a particular signature
(structure). Additionally the payload of an event datagram (it's data element), must be a registered Semantic Type
and
must have a prototype definition. Prototypes define the type of an event datagram, it's defaults and create an association
between a datagram, it's Semantic Type
and it's Event Id
Event datagrams are used as one-way transport for transient data objects. Event datagrams are produced by an event
source, emitter or producer (these are synonymous terms). They are consumed by an event sink or consumer. An instance of the event
is typically destroyed after it is received. It's signature or content may not be modified and the datagram may not be forwarded
(although they may be re-transmitted by the fabric). If immutable objects are persisted in a collection they are typically read-only.
Events are intended as light-weight communication packets not tied to a specific transport or session keeping mechanism unlike
conventional messaging systems.
The fabric provides the Event Datagram
which resembles a more conventional message. A prototype abstract implementation
IAbstractDataEvent
is also provided as a basis for the Message Passing Interface. Users may extend the abstract and
create their own event datagrams and factories which may use the fabric to host transmit and cache such objects.
Copyright: Copyright (c) 2010
Company: StreamScape Technologies
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
SEMANTIC_TYPE_NAME |
DEFAULT_SERIAL_VERSION_ID
Modifier and Type | Method and Description |
---|---|
void |
addAnnotation(java.lang.String propertyName,
java.lang.String sdrPath)
Annotates (exports the value) of a specified data field in the class denoted by the
Semantic Type . |
boolean |
canConvertEventProperty(java.lang.String propertyName,
PropertyType propertyType)
Checks if the value of the specified property can be converted to the object of the specified type.
|
void |
clearEventProperties()
Clears all the properties.
|
boolean |
existsEventProperty(java.lang.String name)
Checks if the property with the specified name exists.
|
java.util.Set |
getAnnotatedProperties()
Returns a list of the annotated properties.
|
EventAnnotation |
getAnnotation(java.lang.String propertyName)
Returns an
EventAnnotation object corresponding to the annotated property with the specified name. |
java.lang.String |
getCorrelationId()
Returns a string version of the correlation identifier.
|
byte[] |
getCorrelationIdAsBytes()
Returns the correlation identifier as a byte array.
|
java.math.BigDecimal |
getEventBigDecimalProperty(java.lang.String name)
Returns the value of the
BigDecimal property with the specified name. |
boolean |
getEventBooleanProperty(java.lang.String name)
Returns the value of the
Boolean property with the specified name. |
byte |
getEventByteProperty(java.lang.String name)
Returns the value of the
Byte property with the specified name. |
double |
getEventDoubleProperty(java.lang.String name)
Returns the value of the
Double property with the specified name. |
long |
getEventExpiration()
Returns the expiration time of the event.
|
float |
getEventFloatProperty(java.lang.String name)
Returns the value of the
Float property with the specified name. |
int |
getEventIntProperty(java.lang.String name)
Returns the value of the
Integer property with the specified name. |
long |
getEventLongProperty(java.lang.String name)
Returns the value of the
Long property with the specified name. |
java.lang.Object |
getEventObjectProperty(java.lang.String name)
Returns the value of the
Object property with the specified name. |
java.util.Set |
getEventPropertyNames()
Returns a list of existing property names.
|
PropertyType |
getEventPropertyType(java.lang.String propertyName)
Returns the type of the event property with the specified name.
|
short |
getEventShortProperty(java.lang.String name)
Returns the value of the
Short property with the specified name. |
java.lang.String |
getEventStringProperty(java.lang.String name)
Returns the value of the
String property with the specified name. |
java.lang.String |
getForwardTo()
Returns the
Event Identifier that an event consumer may use to forward a
(shallow) cloned instance of this event. |
AccessControl |
getPermissions()
Returns the access control object for this data event.
|
byte |
getReadAccess()
Returns
ReadAccess byte permission flag indicating the read access level for
the critical body parts of this object. |
java.lang.String |
getReplyTo()
Returns the
Event Identifier that an event consumer may use to send a
reply or acknowledgment on. |
java.lang.String |
getSecurityAssertionToken()
Returns the security assertion token of the event.
|
byte[] |
getSecurityAssertionTokenAsBytes()
Returns the security assertion token of the event.
|
byte |
getTransmitAccess()
Returns a
TransmitAccess byte permission flag indicating the scope of this event datagram
indicating whether it may be re-transmitted or re-sent to another destination. |
byte |
getWriteAccess()
Returns a
WriteAccess byte permission flag indicating the write access level for
the critical body parts of this object. |
boolean |
hasAnnotatedProperties()
Checks if the event has annotated properties.
|
boolean |
isProtected()
Returns
true if this data object has protected elements. |
void |
protect(java.lang.String principal,
byte[] credential,
AccessControl permissions)
Protects the payload portion of the object using the supplied principal
and credential.
|
void |
removeAnnotation(java.lang.String propertyName)
Removes the specified annotated property from the datagram.
|
void |
removeEventProperty(java.lang.String name)
Removes the event property with the specified name.
|
void |
resetReplyTo()
Sets the event
replyTo parameter to null . |
void |
setCorrelationId(java.lang.String correlationId)
Sets the optional correlation identifier.
|
void |
setCorrelationIdAsBytes(byte[] correlationId)
Sets the optional correlation identifier as a byte array.
|
void |
setDurable(boolean isDurable)
Sets the EventGram's durability flag.
|
void |
setEventBigDecimalProperty(java.lang.String name,
java.math.BigDecimal value)
Sets the specified value of a
BigDecimal property with the specified name. |
void |
setEventBigDecimalProperty(java.lang.String name,
int precision,
int scale)
Sets a template value of a
BigDecimal property with the specified name. |
void |
setEventBooleanProperty(java.lang.String name,
boolean value)
Sets the specified value of a
Boolean property with the specified name. |
void |
setEventByteProperty(java.lang.String name,
byte value)
Sets the specified value of a
Byte property with the specified name. |
void |
setEventDoubleProperty(java.lang.String name,
double value)
Sets the specified value of a
Double property with the specified name. |
void |
setEventExpiration(long expiration)
Sets the specified expiration time of the event.
|
void |
setEventFloatProperty(java.lang.String name,
float value)
Sets the specified value of a
Float property with the specified name. |
void |
setEventGroupId(java.lang.String group)
Sets the optional field that allows developers to group this event with others
of a similar type or within a sequence.
|
void |
setEventIntProperty(java.lang.String name,
int value)
Sets the specified value of a
Integer property with the specified name. |
void |
setEventKey(java.lang.String key)
Sets an optional field that uniquely identifies this event type instance.
|
void |
setEventLongProperty(java.lang.String name,
long value)
Sets the specified value of a
Long property with the specified name. |
void |
setEventObjectProperty(java.lang.String name,
java.lang.Object value)
Sets a user defined property for this event datagram.
|
void |
setEventShortProperty(java.lang.String name,
short value)
Sets the specified value of a
Short property with the specified name. |
void |
setEventStringProperty(java.lang.String name,
java.lang.String value)
Sets the specified value of a
String property with the specified name. |
void |
setFinal()
Causes the event to remove its internal data (such as Annotations)
after a final preparation for sending (i.e.
|
void |
setForwardTo(java.lang.String eventId)
Sets the
Event Identifier that an event consumer may use to forward a (shallow)
cloned instance of this event. |
void |
setReplyTo(java.lang.String eventId)
Sets the
Event Identifier that an event consumer may use to send a
reply or acknowledgment on. |
void |
setSecurityAssertionToken(java.lang.String token)
Sets the specified security assertion token.
|
void |
setSecurityAssertionTokenAsBytes(byte[] token)
Sets the specified security assertion token.
|
void |
unprotect(java.lang.String principal,
byte[] credential)
Un-protects the data element(s) that are made inaccessible by the
protect(java.lang.String, byte[], com.streamscape.sdo.security.AccessControl)
method. |
clone, getDurable, getEventGroupId, getEventId, getEventKey, getEventSource, getTimestamp
getSerialVersionUID
static final java.lang.String SEMANTIC_TYPE_NAME
void setEventKey(java.lang.String key)
key
- the event key to be set.SDORuntimeException
- if the event is coalesced (locked for editing).void setEventGroupId(java.lang.String group)
SDORuntimeException
- if the event is coalesced (locked for editing).java.lang.String getCorrelationId()
byte[] getCorrelationIdAsBytes()
void setCorrelationId(java.lang.String correlationId)
correlationId
- the event correlation identifier to be set.SDORuntimeException
- if the event is coalesced (locked for editing).void setCorrelationIdAsBytes(byte[] correlationId)
correlationId
- the event correlation identifier to be set.SDORuntimeException
- if the event is coalesced (locked for editing).java.lang.String getSecurityAssertionToken()
void setSecurityAssertionToken(java.lang.String token)
token
- the event security assertion token to be set.SDORuntimeException
- if the event is coalesced (locked for editing).byte[] getSecurityAssertionTokenAsBytes()
void setSecurityAssertionTokenAsBytes(byte[] token)
token
- the event security assertion token to be set.SDORuntimeException
- if the event is coalesced (locked for editing).void setReplyTo(java.lang.String eventId) throws SDOFormatException
Event Identifier
that an event consumer may use to send a
reply or acknowledgment on.
The Exchange uses this field to create acknowledgment events.
This setting may not be changed after the event is raised.eventId
- the event identifier to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOFormatException
- if the specified event identifier has invalid format.void resetReplyTo()
replyTo
parameter to null
.SDORuntimeException
- if the event is coalesced (locked for editing).java.lang.String getReplyTo()
Event Identifier
that an event consumer may use to send a
reply or acknowledgment on.replyTo
event parameter.void setForwardTo(java.lang.String eventId) throws SecurityViolationException, SDOFormatException
Event Identifier
that an event consumer may use to forward a (shallow)
cloned instance of this event. The Exchange and other client factories may use
this field to re-transmit the event datagram. This setting may be changed by the user
after the event has been raised. However, if the datagram is protected and the
getTransmitAccess()
method does not return a status that allows the event to be
re-transmitted this method will throw an exception.
Although the actual use of this method is left up to the user, a forwarding
Event Identifier
is primarily intended to assist in the implementation
of a Forward Chaining technique for event processing. This allows events to be
easily composed into micro-flows by using the Acknowledge and Forward operation.
Since the operation typically results in an acknowledgment event being raised every time
the event is forwarded such an event chain provides built-in state reporting and change
capture.
Note that forwarded events retain their original time stamp, source id and properties. However, depending on the implementation the payload may be changed.
eventId
- the event identifier to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SecurityViolationException
- if re-transmission of the event is not allowed.SDOFormatException
- if the specified event identifier has invalid format.java.lang.String getForwardTo()
Event Identifier
that an event consumer may use to forward a
(shallow) cloned instance of this event.forwardTo
event parameter.void protect(java.lang.String principal, byte[] credential, AccessControl permissions) throws SecurityViolationException, SDOException
Read Permissions ReadAccess
WriteAccess
TransmitAccess
Event Id
is not the same as an Exchange Destination
. While destinations are
used as physical units for routing network traffic, event id's are used as logical
units that identify the type of payload.
Read access implies that a consumer other then the security principal can read the contents of the payload but may not modify the actual object. Write permissions imply that a consumer other then the security principal can read and write the object, but may not re-transmit it, for instance as part of a routing mechanism.
If no permissions are set on the object it is expected that consumers other then the principal cannot read or write the content. However in all cases Event Identity Management and similar properties can still be accessed
principal
- the principal to be set.credential
- the credential to be set.permissions
- the permissions to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SecurityViolationException
- if the event is protected.SDOException
- if some internal error occurs.void unprotect(java.lang.String principal, byte[] credential) throws SecurityViolationException, SDOException
protect(java.lang.String, byte[], com.streamscape.sdo.security.AccessControl)
method. The principal and credentials must match.principal
- the principal to be checked.credential
- the credential to be checked.SDORuntimeException
- if the event is coalesced (locked for editing).SecurityViolationException
- if the specified principal and credential are not matched.SDOException
- if some internal error occurs.boolean isProtected()
true
if this data object has protected elements.true
if the event is protected, false
otherwise.AccessControl getPermissions()
protect(java.lang.String, byte[], com.streamscape.sdo.security.AccessControl)
method
describes permission flags and their intended capabilities. The method returns a clone
of AccessControl
. Setting its values has no bearing on object permissions.byte getReadAccess()
ReadAccess
byte permission flag indicating the read access level for
the critical body parts of this object. This flag does not apply to properties.byte getWriteAccess()
WriteAccess
byte permission flag indicating the write access level for
the critical body parts of this object. This flag does not apply to properties.byte getTransmitAccess()
TransmitAccess
byte permission flag indicating the scope of this event datagram
indicating whether it may be re-transmitted or re-sent to another destination.getTransmitAccess
in interface ImmutableEventDatagram
void setDurable(boolean isDurable)
isDurable
- the durability flag to be set.SDORuntimeException
- if the event is coalesced (locked for editing).void setEventExpiration(long expiration)
expiration
- the event expiration time to be set.SDORuntimeException
- if the event is coalesced (locked for editing).long getEventExpiration()
java.lang.Object getEventObjectProperty(java.lang.String name) throws SDOException
Object
property with the specified name.getEventObjectProperty
in interface EventDatagramWithProperties
name
- the specified property name.null
if the property with the specified name is not found.SDOException
- if the specified name has invalid format.boolean getEventBooleanProperty(java.lang.String name) throws SDOException
Boolean
property with the specified name.getEventBooleanProperty
in interface EventDatagramWithProperties
name
- the specified property name.Boolean
property.SDOException
- if the specified name has invalid format or
if the Boolean
property with the specified name is not found.byte getEventByteProperty(java.lang.String name) throws SDOException
Byte
property with the specified name.getEventByteProperty
in interface EventDatagramWithProperties
name
- the specified property name.Byte
property.SDOException
- if the specified name has invalid format or
if the Byte
property with the specified name is not found.short getEventShortProperty(java.lang.String name) throws SDOException
Short
property with the specified name.getEventShortProperty
in interface EventDatagramWithProperties
name
- the specified property name.Short
property.SDOException
- if the specified name has invalid format or
if the Short
property with the specified name is not found.int getEventIntProperty(java.lang.String name) throws SDOException
Integer
property with the specified name.getEventIntProperty
in interface EventDatagramWithProperties
name
- the specified property name.Integer
property.SDOException
- if the specified name has invalid format or
if the Integer
property with the specified name is not found.long getEventLongProperty(java.lang.String name) throws SDOException
Long
property with the specified name.getEventLongProperty
in interface EventDatagramWithProperties
name
- the specified property name.Long
property.SDOException
- if the specified name has invalid format or
if the Long
property with the specified name is not found.float getEventFloatProperty(java.lang.String name) throws SDOException
Float
property with the specified name.getEventFloatProperty
in interface EventDatagramWithProperties
name
- the specified property name.Float
property.SDOException
- if the specified name has invalid format or
if the Float
property with the specified name is not found.double getEventDoubleProperty(java.lang.String name) throws SDOException
Double
property with the specified name.getEventDoubleProperty
in interface EventDatagramWithProperties
name
- the specified property name.Double
property.SDOException
- if the specified name has invalid format or
if the Double
property with the specified name is not found.java.math.BigDecimal getEventBigDecimalProperty(java.lang.String name) throws SDOException
BigDecimal
property with the specified name.getEventBigDecimalProperty
in interface EventDatagramWithProperties
name
- the specified property name.BigDecimal
property.SDOException
- if the specified name has invalid format or
if the BigDecimal
property with the specified name is not found.java.lang.String getEventStringProperty(java.lang.String name) throws SDOException
String
property with the specified name.getEventStringProperty
in interface EventDatagramWithProperties
name
- the specified property name.String
property.SDOException
- if the specified name has invalid format or
if the String
property with the specified name is not found.void setEventObjectProperty(java.lang.String name, java.lang.Object value) throws SDOException
Java Messaging Service
properties. This allows EventGrams to be routed and filtered by a variety
of technologies including SAX and XSLT processors.
If this event datagram has been created from a prototype (by method DatagramFactory.createEvent(String)
),
adding of new properties is not allowed. An exception will be thrown if the specified property does not exist.
Adding of new properties is allowed for uninitialized event datagram intended for a prototype creation
(such datagram can be created by methods like DatagramFactory.newEventInstance(String)
or
DatagramFactory.newEventInstanceFrom(String)
).
The following table describes allowable property type mapping capabilities:
+-------------+------------------------------------------------------------+ | | boolean byte short int long float double BigDecimal String | +------------ +------------------------------------------------------------+ | boolean | X X | | byte | X X X X X X | | short | X X X X X | | int | X X X X | | long | X X X | | float | X X X X | | double | X X X | | BigDecimal | X X | | String | X X X X X X X X X | +-------------+------------------------------------------------------------+The method only allows object versions of java primitive types to be set. Setting the property to
null
is not allowed.setEventObjectProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventBooleanProperty(java.lang.String name, boolean value) throws SDOException
Boolean
property with the specified name.setEventBooleanProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventByteProperty(java.lang.String name, byte value) throws SDOException
Byte
property with the specified name.setEventByteProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventShortProperty(java.lang.String name, short value) throws SDOException
Short
property with the specified name.setEventShortProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist (in a case if this event has been created from a prototype) or
if some internal error occurs.void setEventIntProperty(java.lang.String name, int value) throws SDOException
Integer
property with the specified name.setEventIntProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventLongProperty(java.lang.String name, long value) throws SDOException
Long
property with the specified name.setEventLongProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventFloatProperty(java.lang.String name, float value) throws SDOException
Float
property with the specified name.setEventFloatProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventDoubleProperty(java.lang.String name, double value) throws SDOException
Double
property with the specified name.setEventDoubleProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventBigDecimalProperty(java.lang.String name, java.math.BigDecimal value) throws SDOException
BigDecimal
property with the specified name.
This property in an event prototype is used as a template for all event instances based on this prototype.
All values set by this method will be converted in accordance with the template value
(e.g. precision and scale will be taken from the template value).
If a template value is 0
it is treated as a value with precision 128
and scale 0
.
setEventBigDecimalProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void setEventBigDecimalProperty(java.lang.String name, int precision, int scale) throws SDOException
BigDecimal
property with the specified name.
BigDecimal
value with the specified precision and scale filling it with '9' digits.
E.g. setEventBigDecimalProperty("example", 10, 3)
makes the property "example" with value -9999999.999
.
This method is applicable only if this datagram is an event prototype.
It is used for defining a template property in an event prototype (see setEventBigDecimalProperty(String, java.math.BigDecimal)
)
for further information).
setEventBigDecimalProperty
in interface EventDatagramWithProperties
name
- the property name to be set.precision
- the precision to be set.scale
- the scale to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if this event is not an event prototype or
if precision is not a positive number or
if scale is negative number or
if some internal error occurs.void setEventStringProperty(java.lang.String name, java.lang.String value) throws SDOException
String
property with the specified name.setEventStringProperty
in interface EventDatagramWithProperties
name
- the property name to be set.value
- the property value to be set.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void removeEventProperty(java.lang.String name) throws SDOException
removeAnnotation(String)
instead).
If this event datagram has been created from a prototype (by method DatagramFactory.createEvent(String)
),
removing of existing properties is not allowed. An exception will be thrown if the specified property exists.
Removing of existing properties is allowed for uninitialized event datagram intended for a prototype creation
(such datagram can be created by methods like DatagramFactory.newEventInstance(String)
or
DatagramFactory.newEventInstanceFrom(String)
).
removeEventProperty
in interface EventDatagramWithProperties
name
- the name of the property to be removed.SDORuntimeException
- if the event is coalesced (locked for editing).SDOException
- if the specified name has invalid format or
if the specified property is an annotated property or
if the specified property exists and this event has been created from a prototype or
if some internal error occurs.boolean existsEventProperty(java.lang.String name) throws SDOException
existsEventProperty
in interface EventDatagramWithProperties
name
- the name of the property to be checked.true
if the specified property exists, false
otherwise.SDOException
- if the specified name has invalid format.java.util.Set getEventPropertyNames()
getEventPropertyNames
in interface EventDatagramWithProperties
void clearEventProperties()
clearEventProperties
in interface EventDatagramWithProperties
SDORuntimeException
- if the event is coalesced (locked for editing).PropertyType getEventPropertyType(java.lang.String propertyName) throws SDOException
getEventPropertyType
in interface EventDatagramWithProperties
propertyName
- the specified property name.null
if the property with the specified name is not found.SDOException
- if the specified name has invalid format.boolean canConvertEventProperty(java.lang.String propertyName, PropertyType propertyType) throws SDOException
canConvertEventProperty
in interface EventDatagramWithProperties
propertyName
- the name of the property to be checked.propertyType
- the specified property type.true
if the specified property value can be converted to specified type instance, false
otherwise.SDOException
- if the specified name has invalid format.void addAnnotation(java.lang.String propertyName, java.lang.String sdrPath) throws SecurityViolationException, SDOException
Semantic Type
. In EventGram parlance an annotated datagram is an object
that contains additional information in it's header that refers (or is a subset of) the
datagram's payload. It is expected that the payload object referenced by Semantic Type
is part of the object's data structure prior to invocation of this method.
Annotated properties are populated with values derived from field elements of the data class.
The event source factory uses Java reflection to inspect the class and extract the specified
field elements prior to transmitting the event. This allows EventGrams to produce
secured content and still route and filter the datagrams by annotated content. The annotated
classes must be part of the Structured Data Object
definition.
If this event datagram has been created from a prototype (by method DatagramFactory.createEvent(String)
),
adding of new properties is not allowed. An exception will be thrown if the specified property does not exist.
Adding of new properties is allowed for uninitialized event datagram intended for a prototype creation
(such datagram can be created by methods like DatagramFactory.newEventInstance(String)
or
DatagramFactory.newEventInstanceFrom(String)
).
Event models supporting annotations are the following:
AuditEvent
//data
or //severity
.DataEvent
//data
or //data/<data_fields>
.
DeltaEvent
//beforeImage
or //beforeImage/<image_fields>
or
//afterImage
or //afterImage/<image_fields>
.
ExceptionEvent
//errorMessage
or //errorCode
or //severity
.
MapEvent
//map[<index>]
or //map[key='<key>']
or
//map[value='<value>']
.
String
value and
so the type of annotated property will always be String
.
RowArrayEvent
//row[<primary_key_value>]/<column_name>
or
//row[<primary_key_value>]/column[<column_index>]
.
<primary_key_value>;
is the value of the primary key column in the desired
row for annotation.
RowChangeEvent
//rowBefore/<column_name>
or //rowBefore/column[<column_index>]
or //rowAfter/<column_name>
or //rowAfter/column[<column_index>]
.
RowEvent
//row/<column_name>
or //row/column[<column_index>]
.
RowSetEvent
//row[<row_index>]/<column_name>
or
//row[<row_index>]/column[<column_index>]
.
StreamStateEvent
//streamState
or //stateMessage
or //streamPosition
.
TextEvent
//data/text
.
XMLEvent
<test attr="val"> <inside>Test1</inside> <inside>Test2</inside> </test>An annotation with path
//test/inside[2]
makes an event property with String
value equal to Test2
.
//test
makes an event property with String
value equal to
<inside>Test1</inside><inside>Test2</inside>
.
XMPPEvent
//body
.
propertyName
- the name of the property to be added.sdrPath
- the path to the data field to be annotated.SDORuntimeException
- if the event is coalesced (locked for editing).SecurityViolationException
- if the event is write-protected.SDOException
- if the event does not support annotation or
if the specified property does not exist and this event has been created from a prototype or
if some internal error occurs.void removeAnnotation(java.lang.String propertyName) throws SecurityViolationException, SDOException
If this event datagram has been created from a prototype (by method DatagramFactory.createEvent(String)
),
removing of existing properties is not allowed. An exception will be thrown if the specified property exists.
Removing of existing properties is allowed for uninitialized event datagram intended for a prototype creation
(such datagram can be created by methods like DatagramFactory.newEventInstance(String)
or
DatagramFactory.newEventInstanceFrom(String)
).
propertyName
- the name of the annotated property to be removed.SDORuntimeException
- if the event is coalesced (locked for editing).SecurityViolationException
- if the event is write-protected or
if the specified property exists and this event has been created from a prototype orSDOException
- if some internal error occurs.java.util.Set getAnnotatedProperties() throws SecurityViolationException
SecurityViolationException
- the event is read-protected.boolean hasAnnotatedProperties()
true
if the event has annotated properties, false otherwise.
EventAnnotation getAnnotation(java.lang.String propertyName) throws SecurityViolationException, SDOException
EventAnnotation
object corresponding to the annotated property with the specified name.propertyName
- the specified property name.EventAnnotation
object corresponding to the specified property or null
if this property does not exist.SecurityViolationException
- if the event is read-protected.SDOException
- if the specified name is null
or an empty string.void setFinal()
SDORuntimeException
- if the event is coalesced (locked for editing).Copyright © 2015-2024 StreamScape Technologies. All rights reserved.