Common base class for connections to the DOB. More...

#include <Safir/Dob/ConnectionBase.h>

Inheritance diagram for Safir::Dob::ConnectionBase:

Public Member Functions
	ConnectionBase ()
	Constructor. More...

virtual	~ConnectionBase ()
	Destructor. More...

virtual bool	IsOpen () const =0
	Tells if the connection is opened. More...

Non-pending (synchronous) registration of entity handler.
void	RegisterEntityHandler (const Safir::Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const Dob::InstanceIdPolicy::Enumeration instanceIdPolicy, Dob::EntityHandler *const entityHandler) const
	Registration of an entity handler for a given type. More...

void	RegisterEntityHandlerInjection (const Safir::Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const Dob::InstanceIdPolicy::Enumeration instanceIdPolicy, Dob::EntityHandlerInjection *const entityHandlerInjection) const
	Register an entity handler that also gets informed about injected entities. More...

Pending (asynchronous) registration of entity handler.
void	RegisterEntityHandlerPending (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const Dob::InstanceIdPolicy::Enumeration instanceIdPolicy, Dob::EntityHandlerPending *const entityHandlerPending) const
	Pending registration of a handler for a given entity type. More...

Non-pending (synchronous) registration of service handler.
void	RegisterServiceHandler (const Safir::Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, Dob::ServiceHandler *const serviceHandler) const
	Register a service handler for a given type. More...

Pending (asynchronous) registration of service handler.
void	RegisterServiceHandlerPending (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, Dob::ServiceHandlerPending *const serviceHandlerPending) const
	Pending registration of a handler for a given service type. More...

Unregistration
void	UnregisterHandler (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId) const
	Unregister of an entity handler or a service handler. More...

Message subscriptions
void	SubscribeMessage (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::ChannelId &channelId, Dob::MessageSubscriber *const messageSubscriber) const
	Set up subscription for messages of a certain type and its subclasses. More...

void	SubscribeMessage (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::ChannelId &channelId, const bool includeSubclasses, Dob::MessageSubscriber *const messageSubscriber) const
	Set up subscription for messages of a certain type (additional parameters). More...

void	UnsubscribeMessage (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::ChannelId &channelId, Dob::MessageSubscriber *const messageSubscriber) const
	Remove a message subscription made by the given subscriber. More...

void	UnsubscribeMessage (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::ChannelId &channelId, const bool includeSubclasses, Dob::MessageSubscriber *const messageSubscriber) const
	Remove a message subscription made by the given subscriber (additional parameters). More...

Entity subscriptions
void	SubscribeEntity (const Dob::Typesystem::TypeId typeId, Dob::EntitySubscriber *const entitySubscriber) const
	Set up subscription for instances of an entity type and its subclasses. More...

void	SubscribeEntity (const Dob::Typesystem::TypeId typeId, const bool includeUpdates, const bool includeSubclasses, const bool restartSubscription, Dob::EntitySubscriber *const entitySubscriber) const
	Subscription for an entity type (additional parameters). More...

void	SubscribeEntity (const Dob::Typesystem::EntityId &entityId, const bool includeUpdates, const bool restartSubscription, Dob::EntitySubscriber *const entitySubscriber) const
	Set up subscription for a specific instance of an entity type. More...

void	UnsubscribeEntity (const Dob::Typesystem::TypeId typeId, Dob::EntitySubscriber *const entitySubscriber) const
	Remove an entity subscription made by the given subscriber. More...

void	UnsubscribeEntity (const Dob::Typesystem::TypeId typeId, const bool includeSubclasses, Dob::EntitySubscriber *const entitySubscriber) const
	Remove an entity subscription made by the given subscriber (additional parameters). More...

void	UnsubscribeEntity (const Dob::Typesystem::EntityId &entityId, Dob::EntitySubscriber *const entitySubscriber) const
	Remove an entity instance subscription made by the given subscriber. More...

Registration subscriptions
void	SubscribeRegistration (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const bool includeSubclasses, const bool restartSubscription, Dob::RegistrationSubscriber *const registrationSubscriber) const
	Set up subscription for notifications about when a specific handler for an entity type or a service type is registered and unregistered. More...

void	UnsubscribeRegistration (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const bool includeSubclasses, Dob::RegistrationSubscriber *const registrationSubscriber) const
	Removes a registration subscription. More...

Send messages
void	Send (const Dob::MessagePtr &message, const Dob::Typesystem::ChannelId &channelId, Dob::MessageSender *const messageSender) const
	Send a message on the specified channel. More...

Requests
Dob::RequestId	CreateRequest (const Dob::EntityPtr &request, const Dob::Typesystem::HandlerId &handlerId, Dob::Requestor *const requestor) const
	Request to a handler to create an entity instance without specifying the instanceId. More...

Dob::RequestId	CreateRequest (const Dob::EntityPtr &request, const Dob::Typesystem::InstanceId &instanceId, const Dob::Typesystem::HandlerId &handlerId, Dob::Requestor *const requestor) const
	Request to a handler to create a specific entity instance. More...

Dob::RequestId	UpdateRequest (const Dob::EntityPtr &request, const Dob::Typesystem::InstanceId &instanceId, Dob::Requestor *const requestor) const
	Send an update request on an existing entity instance. More...

Dob::RequestId	DeleteRequest (const Dob::Typesystem::EntityId &entityId, Dob::Requestor *const requestor) const
	Send a delete request on an existing entity instance. More...

Dob::RequestId	ServiceRequest (const Dob::ServicePtr &request, const Dob::Typesystem::HandlerId &handlerId, Dob::Requestor *const requestor) const
	Send a request to the given service handler. More...

Entity Owners
void	SetChanges (const Dob::EntityPtr &entity, const Dob::Typesystem::InstanceId &instanceId, const Dob::Typesystem::HandlerId &handlerId) const
	Merge the changed members of an entity straight into the pool (the given handler must be the owner). More...

void	SetAll (const Dob::EntityPtr &entity, const Dob::Typesystem::InstanceId &instanceId, const Dob::Typesystem::HandlerId &handlerId) const
	Allows an entity handler to create or update an entity. More...

void	Delete (const Dob::Typesystem::EntityId &entityId, const Dob::Typesystem::HandlerId &handlerId) const
	Allows an entity handler to delete a specific owned entity instance. More...

void	DeleteAllInstances (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId) const
	Allows an entity handler to delete all owned instances. More...

Get iterators
Dob::EntityIterator	GetEntityIterator (const Dob::Typesystem::TypeId typeId, const bool includeSubclasses) const
	Retreives an STL compliant iterator to iterate over created instances. More...

Read operations
const Dob::EntityProxy	Read (const Dob::Typesystem::EntityId &entityId) const
	Read an entity from the distributed object pool. More...

bool	IsCreated (const Dob::Typesystem::EntityId &entityId) const
	Check if an instance of an entity is created or not. More...

Dob::Typesystem::Int64	GetNumberOfInstances (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId, const bool includeSubclasses) const
	This method is used to get the number of instances of an entity that exists. More...

Dob::InstanceIdPolicy::Enumeration	GetInstanceIdPolicy (const Dob::Typesystem::TypeId typeId, const Dob::Typesystem::HandlerId &handlerId) const
	This method is used to get the instanceIdPolicy for a specific class and handler. More...

Exit dispatch
void	ExitDispatch () const
	Interrupt the ongoing Dispatch even if all data to the application have not been distpatched. More...

Friends
class	ConnectionAspectBase

Detailed Description

Common base class for connections to the DOB.

There are methods for setting up subscription, register handlers, set and delete entities etc.

Constructor & Destructor Documentation

Safir::Dob::ConnectionBase::ConnectionBase ( )

Constructor.

virtual Safir::Dob::ConnectionBase::~ConnectionBase ( )

virtual

Destructor.

Member Function Documentation

Dob::RequestId Safir::Dob::ConnectionBase::CreateRequest	(	const Dob::EntityPtr &	request,
		const Dob::Typesystem::HandlerId &	handlerId,
		Dob::Requestor *const	requestor
	)		const

Request to a handler to create an entity instance without specifying the instanceId.

If the handler is registered as "HandlerDecidesInstanceId" the InstanceId of the entity to be created is determined by the application, and the requestor is told which InstanceId will be used by the EntityIdResponse. If the handler is registered as "RequestorDecidesInstanceId" an InstanceId will be randomly generated and included in the request. This InstanceId must be used by the handler as the new instance number.

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending of the create request. When the overflow situation is dissolved, the application is notified by the Requestor::OnNotRequestOverflow callback, which should trig the resending.

Parameters

[in]	request	Entity requested to be created.
[in]	handlerId	Handler id.
[in]	requestor	Requestor for response and notification about overflow status.

Returns: Request id that can be used to match sent request with the response.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

Dob::RequestId Safir::Dob::ConnectionBase::CreateRequest	(	const Dob::EntityPtr &	request,
		const Dob::Typesystem::InstanceId &	instanceId,
		const Dob::Typesystem::HandlerId &	handlerId,
		Dob::Requestor *const	requestor
	)		const

Request to a handler to create a specific entity instance.

If the handler is registered as "RequestorDecidesInstanceId" the Requestor must specify which instance is to be created. (If it doesnt care it can use the method above that will generate one randomly.) If the Requestor wants a random instance, but needs to know which instance will get created it can use Dob:Typesystem:InstanceId::GenerateRandom() to generate an InstanceId to pass to this method

Note that it is illegal to call this method if the handler is registered as "HandlerDecidesInstanceId".

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending of the entity create request. When the overflow situation is dissolved, the application is notified by the Requestor::OnNotRequestOverflow callback, which should trig the resending.

Parameters

[in]	request	Entity requested to be created.
[in]	instanceId	Instance id.
[in]	handlerId	Handler id.
[in]	requestor	Requestor for response and notification about overflow status.

Returns: Request id that can be used to match sent request with the response.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

void Safir::Dob::ConnectionBase::Delete	(	const Dob::Typesystem::EntityId &	entityId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

Allows an entity handler to delete a specific owned entity instance.

Used to delete a specific owned instance. Does nothing if the instance does not exist.

Parameters

[in]	entityId	Id of the entity to delete.
[in]	handlerId	Handler id.

Exceptions

Safir::Dob::AccessDeniedException	The instance is owned by another handler.
Safir::Dob::GhostExistsException	There is a ghost instance that hasn't been injected.

void Safir::Dob::ConnectionBase::DeleteAllInstances	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

Allows an entity handler to delete all owned instances.

Used to delete all instances owned by the caller.

Parameters

[in]	typeId	Entity type.
[in]	handlerId	Handler id.

Dob::RequestId Safir::Dob::ConnectionBase::DeleteRequest	(	const Dob::Typesystem::EntityId &	entityId,
		Dob::Requestor *const	requestor
	)		const

Send a delete request on an existing entity instance.

A delete request will be sent to the handler that owns (has created) the entity.

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending of the entity delete request. When the overflow situation is dissolved, the application is notified by the Requestor::OnNotRequestOverflow callback, which should trig the resending.

Parameters

[in]	entityId	EntityId of the entity to be deleted.
[in]	requestor	Requestor for response and notification about overflow status.

Returns: Request id that can be used to match sent request with the response.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

void Safir::Dob::ConnectionBase::ExitDispatch ( ) const

Interrupt the ongoing Dispatch even if all data to the application have not been distpatched.

The dispatch-event will be automatically set to trigger a new Dispatch again. This can be used to ensure that too much time is not spent dispatching in a time-critical app.

Dob::EntityIterator Safir::Dob::ConnectionBase::GetEntityIterator	(	const Dob::Typesystem::TypeId	typeId,
		const bool	includeSubclasses
	)		const

Retreives an STL compliant iterator to iterate over created instances.

The iterator addresses the first created entity instance of the given type. If there are no created instances an iterator representing "end" will be returned.

Example use: for (EntityIterator it = m_connection.GetEntityIterator(Entity::ClassTypeId,true); it != Safir::Dob::EntityIterator(); ++it) { do something with it. }

Parameters

[in]	typeId	Entity type.
[in]	includeSubclasses	True => Iterate over subclass instances False => No subclasses will be included.

Dob::InstanceIdPolicy::Enumeration Safir::Dob::ConnectionBase::GetInstanceIdPolicy	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

This method is used to get the instanceIdPolicy for a specific class and handler.

Parameters

[in]	typeId	The type of the class the handler is registered for.
[in]	handlerId	Get instanceIdPolicy for this handler.

Returns: instanceIdPolicy Specifies if the handler expects instance ids in create requests to be assigned by the requestor or if the handler assigns them by itself.

Exceptions

Safir::Dob::NotFoundException The given handlerId has not registered the given class.

Dob::Typesystem::Int64 Safir::Dob::ConnectionBase::GetNumberOfInstances	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const bool	includeSubclasses
	)		const

This method is used to get the number of instances of an entity that exists.

Parameters

[in]	typeId	The type of the class whose instances we're counting.
[in]	handlerId	Count only instances owned by this handler (use HandlerId::ALL_HANDLERS to get all handlers).
[in]	includeSubclasses	Include subclasses when counting instances.

bool Safir::Dob::ConnectionBase::IsCreated ( const Dob::Typesystem::EntityId & entityId ) const

Check if an instance of an entity is created or not.

This method will return true if the given entity instance is created.

Note that the only time that you can really trust this information is if you're the one that has created the entity instance and no one is overregistering a handler with the same id as yours. Otherwise there is no guarantee that the instance still is created immediately after this call. The owner may be deleting it right after you asked, or your handler may have been revoked but you have not yet received a Revoke status. Use with care!

Parameters

[in] entityId Entity instance to check existence of.

Returns: True if the entity instance is created, otherwise false.

virtual bool Safir::Dob::ConnectionBase::IsOpen ( ) const

pure virtual

Tells if the connection is opened.

Returns: True if the connection is open, otherwise false.

Implemented in Safir::Dob::Connection, and Safir::Dob::SecondaryConnection.

const Dob::EntityProxy Safir::Dob::ConnectionBase::Read ( const Dob::Typesystem::EntityId & entityId ) const

Read an entity from the distributed object pool.

Gets the current version of the entity that matches the given entity id.

Parameters

[in] entityId Entity id of the entity to read.

Returns: Entity read from the distributed object pool.

Exceptions

Safir::Dob::NotFoundException The specified instance of the entity does not exist.

void Safir::Dob::ConnectionBase::RegisterEntityHandler	(	const Safir::Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const Dob::InstanceIdPolicy::Enumeration	instanceIdPolicy,
		Dob::EntityHandler *const	entityHandler
	)		const

Registration of an entity handler for a given type.

Used to make a non-pending registration for a handler for a given type. Upon return from this method the given handler is guaranteed to be registered. (Any existing handler with the same id will be revoked.)

This is the preferred registration method to be used for a handler that has no need to get external entity injections (for example when there is no redundancy).

There can be any number of registered handlers for a type as long as each handler has a unique id.

Note that if you have a configuration where more than one application (connection) is registering the same type/handler, your own registration can still be revoked by another application.

Parameters

[in]	typeId	Entity type to register.
[in]	handlerId	Handler id.
[in]	instanceIdPolicy	Specifies if the handler expects instance ids in create requests to be assigned by the requestor (normal case) or if the handler assigns them by itself.
[in]	entityHandler	Callback consumer object.

void Safir::Dob::ConnectionBase::RegisterEntityHandlerInjection	(	const Safir::Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const Dob::InstanceIdPolicy::Enumeration	instanceIdPolicy,
		Dob::EntityHandlerInjection *const	entityHandlerInjection
	)		const

Register an entity handler that also gets informed about injected entities.

Used to make a non-pending registration for a handler for a given type when the handler also needs to be informed when an entity instance is about to be injected in the system. Upon return from this method the given handler is guaranteed to be registered.

There are two typical cases when entities are injected outside the control of a registered handler:

Reception of persistent entity instances.
Reception of entity instances from an external system installation (multi-owned entities).

After registration, any persistent data will be transfered to the handler via EntityInjectionBase::OnInjectedNewEntity callbacks. When all persistent data have been transfered the handler is notified by the callback EntityInjectionBase::OnInitialInjectionsDone. This callback is guaranteed to be invoked even when there is no persistent data at all.

Parameters

[in]	typeId	Entity type to register.
[in]	handlerId	Handler id.
[in]	instanceIdPolicy	Specifies if the handler expects instance ids in create requests to be assigned by the requestor (normal case) or if the handler assigns them by itself.
[in]	entityHandlerInjection	Callback consumer object.

void Safir::Dob::ConnectionBase::RegisterEntityHandlerPending	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const Dob::InstanceIdPolicy::Enumeration	instanceIdPolicy,
		Dob::EntityHandlerPending *const	entityHandlerPending
	)		const

Pending registration of a handler for a given entity type.

Used to make a pending registration of a handler for a given type. Upon return from this method the given handler is registered as pending. In case an existing handler with the same handler id isn't already registered the Dob will immediately promote this handler to be the registered one.

The consumer is informed via callbacks of any change of the registration status (Completed or Revoked).

This method is to be used by applications that handles redundancy. The typical scenario is that two or more application instances make a pending registration with the same handler id. The Dob will assure that one of the handlers is promoted to registered and all others are pending. If there are several types involved in the redundancy switch it is often the case that you want just one application (the active one) to have all types registered. To achieve this, all applications make a pending registration for one of the types. The application that receives the Completed status then makes a non-pending registration for the remaining types using method RegisterEntityHandler() (or RegisterEntityHandlerInjection()).

Parameters

[in]	typeId	Entity type to register.
[in]	handlerId	Handler id.
[in]	instanceIdPolicy	Specifies if the handler expects instance ids in create requests to be assigned by the requestor (normal case) or if the handler assigns them by itself.
[in]	entityHandlerPending	Callback consumer object.

void Safir::Dob::ConnectionBase::RegisterServiceHandler	(	const Safir::Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		Dob::ServiceHandler *const	serviceHandler
	)		const

Register a service handler for a given type.

See also: RegisterEntityHandler

Parameters

[in]	typeId	Service type to register.
[in]	handlerId	Handler id.
[in]	serviceHandler	Callback consumer object.

void Safir::Dob::ConnectionBase::RegisterServiceHandlerPending	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		Dob::ServiceHandlerPending *const	serviceHandlerPending
	)		const

Pending registration of a handler for a given service type.

See also: RegisterEntityHandlerPending

Parameters

[in]	typeId	Service type to register.
[in]	handlerId	Handler id.
[in]	serviceHandlerPending	Callback consumer object.

void Safir::Dob::ConnectionBase::Send	(	const Dob::MessagePtr &	message,
		const Dob::Typesystem::ChannelId &	channelId,
		Dob::MessageSender *const	messageSender
	)		const

Send a message on the specified channel.

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending the message. When the overflow situation is dissolved, the application is notified by the MessageSender::OnNotMessageOverflow callback, which should trig the resending.

Parameters

[in]	message	Message to send.
[in]	channelId	Channel id.
[in]	messageSender	MessageSender for notification about overflow status.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

Dob::RequestId Safir::Dob::ConnectionBase::ServiceRequest	(	const Dob::ServicePtr &	request,
		const Dob::Typesystem::HandlerId &	handlerId,
		Dob::Requestor *const	requestor
	)		const

Send a request to the given service handler.

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending of the service request. When the overflow situation is dissolved, the application is notified by the Requestor::OnNotRequestOverflow callback, which should trig the resending.

Parameters

[in]	request	The service request.
[in]	handlerId	Service handler id.
[in]	requestor	Requestor for service response and notification about overflow status.

Returns: Request id that can be used to match sent request with the response.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

void Safir::Dob::ConnectionBase::SetAll	(	const Dob::EntityPtr &	entity,
		const Dob::Typesystem::InstanceId &	instanceId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

Allows an entity handler to create or update an entity.

A call to SetAll will replace all members of any existing entity with the given entity. I.e. the DOB will not merge the changes with any existing data, but will instead completely replace the old data. Use the SetChanges() method to make the DOB merge the data into the pool.

Special care must be taken when the owner sets an entity that contains pointers (Entity ids) to other entity instances, and the lifetime of the pointed-to instance is completly connected to the lifetime of the referer. In this case the owner must traverse the object-graph and any unreferenced instance must be deleted.

Parameters

[in]	entity	Entity to create or update.
[in]	instanceId	Instance id.
[in]	handlerId	Handler id.

Exceptions

Safir::Dob::AccessDeniedException	The instance is owned by another handler.
Safir::Dob::GhostExistsException	There is a ghost instance that hasn't been injected.

void Safir::Dob::ConnectionBase::SetChanges	(	const Dob::EntityPtr &	entity,
		const Dob::Typesystem::InstanceId &	instanceId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

Merge the changed members of an entity straight into the pool (the given handler must be the owner).

All members of the given entity that are marked as changed will be merged into the current object in the pool. If the object is not already set in the pool the entity will be set without any merging.

Parameters

[in]	entity	Entity to create or update.
[in]	instanceId	Instance id.
[in]	handlerId	Handler id.

Exceptions

Safir::Dob::AccessDeniedException	The instance is owned by another handler.
Safir::Dob::GhostExistsException	There is a ghost instance that hasn't been injected.

void Safir::Dob::ConnectionBase::SubscribeEntity	(	const Dob::Typesystem::TypeId	typeId,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Set up subscription for instances of an entity type and its subclasses.

The subscriber will receive information about creations, updates and deletes of instances of the given entity type and its subclasses.

When setting up a subscription the user will get initial data for existing entity instances in the form of OnNewEntity callbacks. This is true even when setting up a subscription for an already subscribed entity.

Parameters

[in]	typeId	Type id of the entity to subscribe for.
[in]	entitySubscriber	EntitySubscriber that will receive the entities.

void Safir::Dob::ConnectionBase::SubscribeEntity	(	const Dob::Typesystem::TypeId	typeId,
		const bool	includeUpdates,
		const bool	includeSubclasses,
		const bool	restartSubscription,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Subscription for an entity type (additional parameters).

Overloaded method that gives the user the ability to a determine more details conscerning the subscription.

Parameters

[in]	typeId	Type id of the entity to subscribe for.
[in]	includeUpdates	True => Subscription includes update, as well as create and delete. False => Subscription includes no updates, only create and deletion.
[in]	includeSubclasses	True => Subscription for this entity type and all its subclasses. False => No subclasses will be included.
[in]	restartSubscription	True=> OnNewEntity callbacks are generated even if the subscription already exists. False=> OnNewEntity callbacks are generated only for instances that are not previously subscribed.
[in]	entitySubscriber	EntitySubscriber that will receive the entities.

void Safir::Dob::ConnectionBase::SubscribeEntity	(	const Dob::Typesystem::EntityId &	entityId,
		const bool	includeUpdates,
		const bool	restartSubscription,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Set up subscription for a specific instance of an entity type.

When setting up a subscription the user will get initial data in the form of a OnNewEntity callback with the current state for the subscribed entity (if created).

Parameters

[in]	entityId	Entity id of the entity to subscribe for.
[in]	includeUpdates	True => Subscription includes update, as well as create and delete. False => Subscription includes no updates, only create and deletion.
[in]	restartSubscription	True=> An OnNewEntity callback will be generated even if the subscription already exists. False=> An OnNewEntity callback is generated only if the instance is not previously subscribed.
[in]	entitySubscriber	EntitySubscriber that will receive the entities.

void Safir::Dob::ConnectionBase::SubscribeMessage	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::ChannelId &	channelId,
		Dob::MessageSubscriber *const	messageSubscriber
	)		const

Set up subscription for messages of a certain type and its subclasses.

The subscriber can subscribe for messages sent on a specific cannel, or by using the constant Dob::Typesystem::ChannelId::ALL_CHANNELS, subscribe for all messages of the given type regardless of the channel id set by the sender.

Calling this method is identical to calling the SubscribeMessage below with includeSubclasses = true.

Parameters

[in]	typeId	Type id of the message to subscribe for.
[in]	channelId	Channel id.
[in]	messageSubscriber	MessageSubscriber that will receive the messages.

void Safir::Dob::ConnectionBase::SubscribeMessage	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::ChannelId &	channelId,
		const bool	includeSubclasses,
		Dob::MessageSubscriber *const	messageSubscriber
	)		const

Set up subscription for messages of a certain type (additional parameters).

Overloaded method that gives the user the ability to determine if the subscription also will include subsclasses.

Parameters

[in]	typeId	Type id of the message or to subscribe for.
[in]	channelId	Channel id.
[in]	includeSubclasses	True => Subscription for this message type and all its subclasses. False => No subclasses will be included.
[in]	messageSubscriber	MessageSubscriber that will receive the messages.

void Safir::Dob::ConnectionBase::SubscribeRegistration	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const bool	includeSubclasses,
		const bool	restartSubscription,
		Dob::RegistrationSubscriber *const	registrationSubscriber
	)		const

Set up subscription for notifications about when a specific handler for an entity type or a service type is registered and unregistered.

Using the constant Dob::Typesystem::HandlerId::ALL_HANDLERS means that the subscriber will receive registrations/unregistrations of any handler for the given type.

Using a specific handler id means that the subscriber will receive only the registrations/unregistrations of the specified handler.

When setting up a subscription the user will get initial information about existing handlers via OnRegistered callbacks.

Parameters

[in]	typeId	Type id of entity or service.
[in]	handlerId	Handler id.
[in]	includeSubclasses	True => Subscription for this entity type or service type and all its subclasses. False => No subclasses will be included.
[in]	restartSubscription	True=> OnRegistered callbacks are generated even if the subscription already exists. False=> OnRegistered callbacks are generated only for handlers that are not previously subscribed.
[in]	registrationSubscriber	RegistrationSubscriber that will receive the subscription response.

void Safir::Dob::ConnectionBase::UnregisterHandler	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId
	)		const

Unregister of an entity handler or a service handler.

Any created entity instance owned by the given handler will be deleted.

This method can also be used to unregister a pending handler.

Using the constant Dob::Typesystem::HandlerId::ALL_HANDLERS means that all handlers for the given type, registered by this connection, will be unregistered.

If the given handler isn't registered the call will be ignored.

Parameters

[in]	typeId	Type id of the entity or service to unregister.
[in]	handlerId	Handler id.

void Safir::Dob::ConnectionBase::UnsubscribeEntity	(	const Dob::Typesystem::TypeId	typeId,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Remove an entity subscription made by the given subscriber.

Removes the subscription for the given type and its subclasses.

If no subscription exists the call will be ignored.

Parameters

[in]	typeId	Type id of the entity to unsubscribe for.
[in]	entitySubscriber	The EntitySubscriber consumer that was used when the subscription was initiated.

void Safir::Dob::ConnectionBase::UnsubscribeEntity	(	const Dob::Typesystem::TypeId	typeId,
		const bool	includeSubclasses,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Remove an entity subscription made by the given subscriber (additional parameters).

Overloaded method that gives the user the ability to determine if unsubscription also will include subsclasses..

Parameters

[in]	typeId	Type id of the entity to unsubscribe for.
[in]	includeSubclasses	True => Unsubscribe for this entity type and all its subclasses. False => Unsubscribe for just this type (no subclasses).
[in]	entitySubscriber	The EntitySubscriber consumer that was used when the subscription was initiated.

void Safir::Dob::ConnectionBase::UnsubscribeEntity	(	const Dob::Typesystem::EntityId &	entityId,
		Dob::EntitySubscriber *const	entitySubscriber
	)		const

Remove an entity instance subscription made by the given subscriber.

If no subscription exists the call will be ignored.

Parameters

[in]	entityId	Entity id of the entity instance.
[in]	entitySubscriber	The EntitySubscriber consumer that was used when the subscription was initiated.

void Safir::Dob::ConnectionBase::UnsubscribeMessage	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::ChannelId &	channelId,
		Dob::MessageSubscriber *const	messageSubscriber
	)		const

Remove a message subscription made by the given subscriber.

Removes the subscription for the given type and its subclasses.

Using the constant Dob::Typesystem::ChannelId::ALL_CHANNELS means that all subscriptions for the given type and its subclasses will be removed.

If no subscription exists the call will be ignored.

Calling this method is identical to calling the UnsubscribeMessage below with includeSubclasses = true.

Parameters

[in]	typeId	Type id of the message to unsubscribe for.
[in]	channelId	Channel id.
[in]	messageSubscriber	The MessageSubscriber consumer that was used when the subscription was initiated.

void Safir::Dob::ConnectionBase::UnsubscribeMessage	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::ChannelId &	channelId,
		const bool	includeSubclasses,
		Dob::MessageSubscriber *const	messageSubscriber
	)		const

Remove a message subscription made by the given subscriber (additional parameters).

Overloaded method that gives the user the ability to determine if unsubscription also will include subsclasses.

Parameters

[in]	typeId	Type id of the message to unsubscribe for.
[in]	channelId	Channel id.
[in]	includeSubclasses	True => Unsubscribe for this message type and all its subclasses. False => No subclasses will be included.
[in]	messageSubscriber	The MessageSubscriber consumer that was used when the subscription was initiated.

void Safir::Dob::ConnectionBase::UnsubscribeRegistration	(	const Dob::Typesystem::TypeId	typeId,
		const Dob::Typesystem::HandlerId &	handlerId,
		const bool	includeSubclasses,
		Dob::RegistrationSubscriber *const	registrationSubscriber
	)		const

Removes a registration subscription.

Using the constant Dob::Typesystem::HandlerId::ALL_HANDLERS means that all registration subscriptions, for the given type id and consumer, are removed.

If no subscription exists the call will be ignored.

Parameters

[in]	typeId	Type id of entity or service.
[in]	handlerId	Handler id.
[in]	includeSubclasses	True => Unsubscribe for this entity type or service type and all its subclasses. False => No subclasses will be included.
[in]	registrationSubscriber	The registrationSubscriber consumer that was used when the subscription was initiated.

Dob::RequestId Safir::Dob::ConnectionBase::UpdateRequest	(	const Dob::EntityPtr &	request,
		const Dob::Typesystem::InstanceId &	instanceId,
		Dob::Requestor *const	requestor
	)		const

Send an update request on an existing entity instance.

An update request will be sent to the handler that owns (has created) the entity.

The application must be prepared to handle the situation that the outgoing send queue is full (OverflowException is thrown). In this case the application is responsible for resending of the entity update request. When the overflow situation is dissolved, the application is notified by the Requestor::OnNotRequestOverflow callback, which should trig the resending.

Parameters

[in]	request	Entity requested to be updated.
[in]	instanceId	Instance id.
[in]	requestor	Requestor for response and notification about overflow status.

Returns: Request id that can be used to match sent request with the response.

Exceptions

Safir::Dob::OverflowException There was an overflow when sending.

Friends And Related Function Documentation

friend class ConnectionAspectBase

friend

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation