IEncryptedObject interface

Declaration

package com.kryptel.storage;

public interface IEncryptedObject {
  UUID GetObjectID() throws Exception;
  IEncryptedObject GetParent() throws Exception;
  int GetObjectFlags() throws Exception;

  byte[] GetAttributeBlock() throws Exception;
  void SetAttributeBlock(byte[] attr, int start, int size) throws Exception;

  boolean StreamExists() throws Exception;
  long StreamSize() throws Exception;
  IEncryptedStream CreateStream(byte comprLevel) throws Exception;
  IEncryptedStream CreateStream(byte[] recData, byte comprLevel) throws Exception;
  IEncryptedStream OpenStream() throws Exception;
  void DeleteStream() throws Exception;

  void MoveTo(IEncryptedObject newParent) throws Exception;

  UUID[] GetChildren() throws Exception;
  IEncryptedObject CreateChildObject() throws Exception;
  IEncryptedObject GetChildObject(UUID id) throws Exception;

  void DeleteChildObject(UUID id) throws Exception;
  void UndeleteChildObject(UUID id, boolean recursive) throws Exception;
}

Description

This interface represents encrypted object (see the description of Kryptel storage model.

Typically, the client first obtains IEncryptedObject of the root object by calling a function of the IEncryptedStorage interface – Create, Open, or GetRootObject. Next, it gets access to the needed object by enumerating or creating the children objects.

Note about deleted objects: objects flagged for deletion (i.e. those with Constants.EFL_OBJECT_DELETED flag set) are read-only; the only modifying operation allowed for them is undelete.

GetObjectID

UUID GetObjectID() throws Exception;

Returns 128-bit object ID. Note that this identifier is not guaranteed to be globally unique, but it is unique between the children of the same parent object.

GetParent

IEncryptedObject GetParent() throws Exception;

Returns a pointer to the parent object or null if the current object is the root of the object tree.

GetObjectFlags

int GetObjectFlags() throws Exception;

Returns object flags (see Constants.EFL_* values).

GetAttributeBlock

byte[] GetAttributeBlock() throws Exception;

Returns the object's attribute block or null if there is none.

You can also check the object's Constants.EFL_ATTRIBUTE_BLOCK flag in order to check the existence of an attribute block.

SetAttributeBlock

void SetAttributeBlock(byte[] attr, int start, int size) throws Exception;

Fetches size bytes starting at start and sets them as the object's attribute block. If the object already has an attribute block, the old block is discarded.

If attr == null or size == 0 then the current attribute block will be removed without setting a new one.

StreamExists

boolean StreamExists() throws Exception;

Returns true if the object has a data stream. An alternate method is to check the object's Constants.EFL_DATA_STREAM flag.

StreamSize

long StreamSize() throws Exception;

Returns the size of the object's data stream. If the object does not have a data stream, Kryptel 7 storage handler returns zero, but other implementations may throw an exception. It is recommended to check StreamExists before calling this function.

CreateStream

IEncryptedStream CreateStream(byte comprLevel) throws Exception;
IEncryptedStream CreateStream(byte[] recData, byte comprLevel) throws Exception;

Creates a data stream and returns its IEncryptedStream. The function will throw an exception if the object already has a data stream. In order to replace an existing stream call DeleteStream function first;

comprLevel

Required compression level from 0 (no compression) to 9 (max compression). See the CT_* named constants in the Constants class.

recData

Agent's recovery data or null if a recovery block is not to be created.

Recovery block, which storage handler creates, just provides a way to locate and decrypt the data stream (see container format for details). The handler operates raw data and does not know what a given data stream contains and how it should be interpreted. The information that the client provides in the recData argument lets a recovery program recognize and correctly recover the user data.

For example, Kryptel file agent stores the file path there, and Kryptel data recovery program uses that information to link the data stream with a specific file. A custom container may use other recovery data (which will, of course, require writing a custom recovery program).

OpenStream

IEncryptedStream OpenStream() throws Exception;

Opens the object's data stream and returns its IEncryptedStream. If the object does not have a data stream, the function throws an exception.

DeleteStream

void DeleteStream() throws Exception;

Delete the object's data stream. If the object does not have a data stream, this function does nothing.

MoveTo

void MoveTo(IEncryptedObject newParent) throws Exception;

Moves the object to the specified parent object.

Note that this operation may change the moved object's ID.

GetChildren

UUID[] GetChildren() throws Exception;

Returns an array of IDs of the children objects or null if the object has no children.

Don't use this function if you need just check the presence of children objects. Call the much faster GetObjectFlags function and check the Constants.EFL_CHILD_OBJECTS flag.

CreateChildObject

IEncryptedObject CreateChildObject() throws Exception;

Creates a new child object and return its IEncryptedObject.

GetChildObject

IEncryptedObject GetChildObject(UUID id) throws Exception;

Find a child object by its object ID and return its IEncryptedObject or null if there is no child with such ID.

DeleteChildObject

void DeleteChildObject(UUID id) throws Exception;

Delete the child object with the specified ID. Depending on the storage capabilities (see Constants.ESTOR_KEEPS_DELETED_OBJECTS flag) this function either actually deletes the object or just sets the object's Constants.EFL_OBJECT_DELETED flag. Note however that the storage handler may initiate storage compression (see IEncryptedStorage.SetCompressionStrategy), during which flagged objects become actually deleted.

If the objects being deleted has children objects, they also get deleted (flagged).

UndeleteChildObject

void UndeleteChildObject(UUID id, boolean recursive) throws Exception;

Undelete an object that is flagged for deletion (i.e. has Constants.EFL_OBJECT_DELETED flag set).

id

Object ID of the child object to be undeleted.

recursive

If this argument is true then all the contained objects will also get undeleted.