Storages Module

The storages module provides a set of storage services allowing an application to store data files, documents, images in a persistent area. The persistent store can be on a file system, in the database or provided by a remote service such as Amazon Simple Storage Service.

Integration

To be able to use the storages module, you will need to add the following line in your GNAT project file:

with "awa_storages";

The Storage_Module type represents the storage module. An instance of the storage module must be declared and registered when the application is created and initialized. The storage module is associated with the storage service which provides and implements the storage management operations. An instance of the Storage_Module must be declared and registered in the AWA application. The module instance can be defined as follows:

with AWA.Storages.Modules;
...
type Application is new AWA.Applications.Application with record
   Storage_Module : aliased AWA.Storages.Modules.Storage_Module;
end record;

And registered in the Initialize_Modules procedure by using:

Register (App    => App.Self.all'Access,
          Name   => AWA.Storages.Modules.NAME,
          Module => App.Storage_Module'Access);

Permissions

Name	Entity type	Description
folder-create	awa_workspace
storage-create	awa_workspace
storage-delete	awa_workspace

Configuration

The storages module defines the following configuration parameters:

Name	Description
storages.storage_root	The path of the directory that contains storage files stored on the local filesystem.
	storage
storages.tmp_storage_root	The path of the directory that contains temporary storage files on the local filesystem.
	tmp
storages.database_max_size	The maximum size of documents store in the database storage.
	100000

Creating a storage

A data in the storage is represented by a Storage_Ref instance. The data itself can be physically stored in a file system (FILE mode), in the database (DATABASE mode) or on a remote server (URL mode). To put a file in the storage space, first create the storage object instance:

Data : AWA.Storages.Models.Storage_Ref;

Then setup the storage mode that you want. The storage service uses this information to save the data in a file, in the database or in a remote service (in the future). To save a file in the store, we can use the Save operation of the storage service. It will read the file and put in in the corresponding persistent store (the database in this example).

Service.Save (Into => Data, Path => Path_To_The_File,
              Storage => AWA.Storages.Models.DATABASE);

Upon successful completion, the storage instance Data will be allocated a unique identifier that can be retrieved by Get_Id or Get_Key.

Getting the data

Several operations are defined to retrieve the data. Each of them has been designed to optimize the retrieval and

The data can be retrieved in a local file. This mode is useful if an external program must be launched and be able to read the file. If the storage mode of the data is FILE, the path of the file on the storage file system is used. For other storage modes, the file is saved in a temporary file. In that case the Store_Local database table is used to track such locally saved data.
The data can be returned as a stream. When the application has to read the data, opening a read stream connection is the most efficient mechanism.

Local file

To access the data by using a local file, we must define a local storage reference:

Data : AWA.Storages.Models.Store_Local_Ref;

and use the Load operation with the storage identifier. When loading locally we also indicate whether the file will be read or written. A file that is in READ mode can be shared by several tasks or processes. A file that is in WRITE mode will have a specific copy for the caller. An optional expiration parameter indicate when the local file representation can expire.

Service.Load (From => Id, Into => Data, Mode => READ, Expire => ONE_DAY);

Once the load operation succeeded, the data is stored on the file system and the local path is obtained by using the Get_Path operation:

Path : constant String := Data.Get_Path;

Storage Service

The Storage_Service provides the operations to access and use the persisent storage. It controls the permissions that grant access to the service for users.

Other modules can be notified of storage changes by registering a listener on the storage module.

Store Service

The AWA.Storages.Stores package defines the interface that a store must implement to be able to save and retrieve a data content. The store can be a file system, a database or a remote store service.

Database store

The AWA.Storages.Stores.Databases store uses the database to save a data content. The data is saved in a specific table in a database blob column. The database store uses another store service to temporarily save the data content in a local file when the application needs a file access to the data.

File System store

The AWA.Storages.Stores.Files store uses the file system to save a data content. Files are stored in a directory tree whose path is created from the workspace identifier and the storage identifier. The layout is such that files belonged to a given workspace are stored in the same directory sub-tree.

The root directory of the file system store is configured through the storage_root and tmp_storage_root configuration properties.

Ada Beans

Name	Description
storageFolder	This bean allows to create a storage folder.
uploadFile	This bean allows to upload a new file in the storage space.
folderList	This bean gives the list of storage folders in the workspace.
storageList	This bean gives the list of storage files associated with a given folder.
storageInfo	This bean gives some information about a document and its folder.

AWA.Storages.Models.Storage_Info

The list of documents for a given folder.

Ada	Name	Description
Identifier	id	the storage identifier.
String	name	the file name.
Date	create_date	the file creation date.
String	uri	the file storage URI.
AWA.Storages.Models.Storage_Type	storage	the file storage URI.
String	mime_type	the file mime type.
Integer	file_size	the file size.
Boolean	is_public	whether the document is public or not.
String	user_name	the user name who uploaded the document.
Integer	thumb_width	the image thumbnail width (or 0).
Integer	thumb_height	the image thumbnail height (or 0).
Identifier	thumbnail_id	the image thumbnail identifier.

AWA.Storages.Models.Folder_Info

The list of folders.

Ada	Name	Description
Identifier	id	the folder identifier.
String	name	the folder name.
Date	create_date	the blog creation date.

Storage Servlet

The Storage_Servlet type is the servlet that allows to retrieve the file content that was uploaded.

Queries

Name	Description
storage-list	Get a list of storage files for a given folder.

Name	Description
storage-folder-list	Get a list of storage folders that a user can see.

Name	Description
storage-get-data	Get the data content of the storage object.
storage-get-local	Get the local data storage that can be used to read locally a storage object.
storage-get-storage	Get the local data storage that can be used to read locally a storage object.
storage-delete-local	Delete the local storage data

Name	Description
storage-info	Get the description of a document.