Overview

Module node_flat [erl svg]

• Description
• Function Index
• Function Details

Copyright © 2006-2012 ProcessOne

Version: 3.0.0-alpha-5, May 23 2012 07:15:12

Behaviours: gen_pubsub_node.

Authors: Christophe Romain (christophe.romain@process-one.net) [web site: http://www.process-one.net/].

To do

• The item table should be handled by the plugin, but plugin that do not want to manage it should be able to use the default behaviour.
• Plugin modules should be able to register to receive presence update send to pubsub.

Description

It is used as a default for all unknown PubSub node type. It can serve as a developer basis and reference to build its own custom pubsub node types.

PubSub plugin nodes are using the gen_node behaviour.

The API isn't stabilized yet. The pubsub plugin development is still a work in progress. However, the system is already useable and useful as is. Please, send us comments, feedback and improvements.

Function Index

Function Details

can_fetch_item/2 *

Determines if the combination of Affiliation and Subscribed are allowed to get items from a node.

create_node/2

create_node_permission/6

del_item/2 *

Delete an item from database.

del_items/2 *

del_state/2 *

Delete a state from database.

delete_item/4

Triggers item deletion.

Default plugin: The user performing the deletion must be the node owner or a publisher, or PublishModel being open.

delete_node/1

purge items of deleted nodes after effective deletion.

delete_subscriptions/4 *

features/0

Returns the node features

first_in_list/2 *

get_affiliation/2

get_entity_affiliations/2

Return the current affiliations for the given user

The default module reads affiliations in the main Mnesia pubsub_state table. If a plugin stores its data in the same table, it should return an empty list, as the affiliation will be read by the default PubSub module. Otherwise, it should return its own affiliation, that will be added to the affiliation stored in the main pubsub_state table.

get_entity_subscriptions/2

Return the current subscriptions for the given user

The default module reads subscriptions in the main Mnesia pubsub_state table. If a plugin stores its data in the same table, it should return an empty list, as the affiliation will be read by the default PubSub module. Otherwise, it should return its own affiliation, that will be added to the affiliation stored in the main pubsub_state table.

get_item/2

Returns an item (one item list), given its reference.

get_item/7

get_item_name/3

Return the name of the node if known: Default is to return node id.

get_items/2

Returns the list of stored items for a given node.

For the default PubSub module, items are stored in Mnesia database.

We can consider that the pubsub_item table have been created by the main mod_pubsub module.

PubSub plugins can store the items where they wants (for example in a relational database), or they can even decide not to persist any items.

If a PubSub plugin wants to delegate the item storage to the default node, they can implement this function like this:

     get_items(NodeId, From) ->
 	   node_default:get_items(NodeId, From).

get_items/6

get_node_affiliations/1

get_node_subscriptions/1

get_nodes_helper/2 *

get_pending_nodes/2

Returns a list of Owner's nodes on Host with pending subscriptions.

get_state/2

Returns a state (one state list), given its reference.

get_states/1

Returns the list of stored states for a given node.

For the default PubSub module, states are stored in Mnesia database.

We can consider that the pubsub_state table have been created by the main mod_pubsub module.

PubSub plugins can store the states where they wants (for example in a relational database).

If a PubSub plugin wants to delegate the states storage to the default node, they can implement this function like this:

     get_states(NodeId) ->
 	   node_default:get_states(NodeId).

get_subscriptions/2

init/3

Called during pubsub modules initialisation. Any pubsub plugin must implement this function. It can return anything.

This function is mainly used to trigger the setup task necessary for the plugin. It can be used for example by the developer to create the specific module database schema if it does not exists yet.

is_subscribed/1 *

new_subscription/4 *

node_to_path/1

options/0

Returns the default pubsub node options.

Example of function return value:

 	 [{deliver_payloads, true},
 	  {notify_config, false},
 	  {notify_delete, false},
 	  {notify_retract, true},
 	  {persist_items, true},
 	  {max_items, 10},
 	  {subscribe, true},
 	  {access_model, open},
 	  {publish_model, publishers},
 	  {max_payload_size, 100000},
 	  {send_last_published_item, never},
 	  {presence_based_delivery, false}]

path_to_node/1

publish_item/6

Publishes the item passed as parameter.

The mechanism works as follow:

• The main PubSub module prepares the item to publish and passes the result of the preparation as a mod_pubsub:pubsubItem() record.
• This function gets the prepared record and several other parameters and can decide to:
  • reject the publication;
  • allow the publication as is, letting the main module perform the database persistance;
  • allow the publication, modifying the record. The main module will store the modified record;
  • allow it, but perform the needed persistance operations.

The selected behaviour depends on the return parameter:

• {error, Reason}: an iq error result will be return. No publication is actually performed.
• true: Publication operation is allowed, based on the unmodified record passed in parameter Item. If the Item parameter contains an error, no subscription will actually be performed.
• {true, Item}: Publication operation is allowed, but the mod_pubsub:pubsubItem() record returned replaces the value passed in parameter Item. The persistance will be performed by the main module.
• {true, done}: Publication operation is allowed, but the mod_pubsub:pubsubItem() will be considered as already stored and no further persistance operation will be performed. This case is used, when the plugin module is doing the persistance by itself or when it want to completly disable persistance.

In the default plugin module, the record is unchanged.

purge_node/2

remove_extra_items/3

This function is used to remove extra items, most notably when the maximum number of items has been reached.

This function is used internally by the core PubSub module, as no permission check is performed.

In the default plugin module, the oldest items are removed, but other rules can be used.

If another PubSub plugin wants to delegate the item removal (and if the plugin is using the default pubsub storage), it can implements this function like this:

     remove_extra_items(NodeId, MaxItems, ItemIds) ->
 	   node_default:remove_extra_items(NodeId, MaxItems, ItemIds).

replace_subscription/2 *

replace_subscription/3 *

set_affiliation/3

set_item/1

Write an item into database.

set_state/1

Write a state into database.

set_subscriptions/4

subscribe_node/8

Accepts or rejects subcription requests on a PubSub node.

The mechanism works as follow:

• The main PubSub module prepares the subscription and passes the result of the preparation as a record.
• This function gets the prepared record and several other parameters and can decide to:
  • reject the subscription;
  • allow it as is, letting the main module perform the database persistance;
  • allow it, modifying the record. The main module will store the modified record;
  • allow it, but perform the needed persistance operations.

The selected behaviour depends on the return parameter:

• {error, Reason}: an IQ error result will be returned. No subscription will actually be performed.
• true: Subscribe operation is allowed, based on the unmodified record passed in parameter SubscribeResult. If this parameter contains an error, no subscription will be performed.
• {true, PubsubState}: Subscribe operation is allowed, but the mod_pubsub:pubsubState() record returned replaces the value passed in parameter SubscribeResult.
• {true, done}: Subscribe operation is allowed, but the mod_pubsub:pubsubState() will be considered as already stored and no further persistance operation will be performed. This case is used, when the plugin module is doing the persistance by itself or when it want to completly disable persistance.

In the default plugin module, the record is unchanged.

terminate/2

Called during pubsub modules termination. Any pubsub plugin must implement this function. It can return anything.

unsub_with_subid/3 *

unsubscribe_node/4

Unsubscribe the Subscriber from the Node.

Overview

Generated by EDoc, May 23 2012, 07:15:12.