API: Storage

Storage

The P2P infrastructure of las2peer provides a distributed data storage architecture. To ensure data consistency when nodes add or leave the network, all data are reproduced and stored redundantly on multiple nodes.

To keep data across node restarts, a node must not change its id! This is guaranteed by setting the node id launch paramter --node-id-seed . Otherwise, a node will generate a random node id per start. See L2pNodeLauncher Commands

What can be stored Any Java object with the Serializable interface can be stored inside the network.

Data model Each object (called Envelope) is identified by a unique id. The developer is free to use any String as identifier. Each service has its own namespace for envelopes. Services cannot access envelopes created by another service.

Read access For each envelope, a list of readers (any Agent wit a key) can be specified. The envelope is encrypted with their keys and only available to them. If the envelope has been made public, the content is not encrypted and accessible by everyone.

Write access Only those agent who signed the envelope is able to write to the envelope. Note that each envelope must have one and only one signing agent at any time.

Request envelopes

Requesting an envelope means fetching it from the network and opening/decrypting them with a specified agent:

Envelope env = Context.get().requestEnvelope(String identifier, Agent using);

If using is not specified, the current main agent is used.

This operation also considers transitive access through group agents.

Create envelopes

Envelopes can be created as follows:

Envelope fresh = Context.get().createEnvelope(String identifier, Agent using);

Again, the default value for using is the main agent. using will be set as signing agent and as the first reader.

Note that at this point, the envelope is not stored to the network yet.

Updating the content

An envelope can contain any Java object that implements the Serializable interface.

Serializable content = new MyCustomObject();
envelope.setContent(content);

Serializable content = envelope.getContent();

Store envelopes

After creating, updating or changing permissions of an envelope, the envelope must be stored to the network. Otherwise, all changes will be lost.

During a store operation, an agent has to be specified (or the default main agent is used). This agent needs to have access to the signing agent of the envelope. Note that the signing agent cannot be changed.

Context.get().storeEnvelope(Envelope env [, Agent using]);

There is also a method that accepts a second argument, an EnvelopeCollisionHandler which is called if someone else pushed a new version to the network after this service has fetched the envelope and before this service has stored the new version of the envelope.

Context.get().storeEnvelope(Envelope env, new EnvelopeCollisionHandler {
  public Envelope onCollision(Envelope toStore, Envelope inNetwork) throws MergeFailedException {
    // update inNetwork Envelope to contain the merged content of both envelopes
    // or throw MergeFailedException on error
  }
});

Reclaim ("delete") envelopes

If an envelope is no longer needed, it can be reclaimed. Note that this is not the same as deleting a file on your local file system as due to the nature of a p2p system, it cannot be guaranteed that the envelope actually disappears from the network. Reclaiming indicates that the space can be freed and the envelope is no longer needed. However, it cannot be enforced that all nodes hosting the envelope will delete them.

To perform this operation, access to the signing agent is needed.

Context.get().reclaimEnvelope(String identifier [, Agent using]);

Permissions

Readers

Readers can be added and removed from an envelope at any time. While adding a reader to an envelope works as expected, removing a member has a slightly but significant different semantic as usual: The nature of a p2p system can only guarantee that all future versions of the envelope are no longer accessible to removed readers. However, old envelope versions may still be available to them. This is why we call this revoking a membership.

env.addReader(Agent reader);
env.revokeReader(Agent reader);
env.hasReader(Agent reader); // check membership

Unencrypted envelope

If the envelope should be readable by anyone, it can be stored unencrypted. Unencrypted envelopes are still signed and thus its authenticity is assured.

To make an envelope public, call

env.setPublic()

To check if the envelope is encrypted call

env.isPrivate()

To make it private again, simply add a reader to the envelope.

Multiple authors

To enable write access for mutliple agents, a group agent has to be specified as signing agent. Afterwards, the envelope can be used as any other envelope, since the singing group agent is automatically unlocked on write:

GroupAgent writer = Context.get().createGroupAgent(Agent[] members);
Context.get().storeAgent(writer);
Envelope env = Context.get().createEnvelope(String identifier, writer);
// modify envelope ...
Context.get().storeEnvelope(writer);

It is important that the group agent is stored to the network before the envelope is stored to the network.

Anonymous

Note that the anonymous agent is only allowed to read unencrypted envelopes. It cannot store any envelope to the network.