BLOB stores (attributes of type Document on ORM level)

Entity attribute of Document type with storeName property for this attribute should be defined. Content (data stored in the database) of such attributes is a meta-information about file - a serialized BlobStoreItem object, not an actual file content.

In case entity is stored in the database using mStorage mixin, DDL generator create nvarchar(2000) field in database and store there BlobStoreItem serialized to JSON.

For Virtual entity developer should implement select method and fill BlobStoreItem manually (for example by parsing file content as done in ubm_form).

In the store definition section of application config developer describe stores. Each store must implement interface described below.

The store class itself provide storing and retrieving file content (based on meta-information stored in the entity attribute).

From client-side POV uploading files to server is separated onto two part. Like in gmail when you send mail with attachment you can attach a file, and gmail send it to server, but you do not send mail itself yet - this is first stage. Result of this stage is information about where file is stored on the server side. When you send email client pass to server email attributes, body and information about attached files. This is the same UnityBase do in the second stage.

Server side usage:

// get dirty (not committed yet) content of my_entity.docAttribute with ID = 12312 as ArrayBuffer
let tmpContent = App.blobStores.getContent(
   {ID: 12312, entity: 'my_entity', attribute: 'blobAttribute', isDirty: true},
   {encoding: 'bin'}
)

// get BLOB content of my_entity.docAttribute with ID = 12312 as base64 string
let base64Content = App.blobStores.getContent(
  {ID: 12312, entity: 'my_entity', attribute: 'blobAttribute'},
  {encoding: 'base64'}
)

// get BLOB content of my_entity.docAttribute with ID = 12312 as string
let base64Content = App.blobStores.getContent(
  {ID: 12312, entity: 'my_entity', attribute: 'blobAttribute'},
  {encoding: 'utf8'}
)

// put a file into  BLOB store
let blobItem = App.blobStores.putContent(
  {ID: 12312, entity: 'my_entity', attribute: 'blobAttribute'},
  '/tpm/someHugeFile.zip',
  { contentIsFilePath: true }
)
// or read file and put it to BLOB store (not committed yet)
let content = fs.readFileSync(__filename, {encoding: 'bin'})
let fn = path.basename(__filename)
let blobItem = App.blobStores.putContent(
  {ID: 12312, entity: 'my_entity', attribute: 'blobAttribute'},
  content
)

// commit blob store
let dataStore = UB.DataStore(my_entity)
dataStore.run('update', {
  execParams: {
	ID: 12312,
	blobAttribute: JSON.stringify(blobItem)
  }
})

Upload file to server

In UnityBase upload file to server is performed in two stages:

1. Upload file to temporary store - on this stage client call setDocument app level method and pass file content to server with an additional parameter isDirty=true, server store file in the temporary place.

2. Client execute insert or update entity method and pass (with other attributes) string, returned on the first stage as a value of Document type attribute. On this stage server see what user want to update/insert Document and, based on Domain information, know what type of store is used for this attribute. Server:

3. Finally, UnityBase update entity and commit database transaction (in case entity is non-virtual)

To enable support for client side large file uploading, set chunk size in mb in ubConfig.json, parameter uiSettings.uploadChunkSizeMb. Also, it's possible to pass different chunkSize to setDocument's params, or pass null or 0 to disable

UB.connection.setDocument(file, {
  entity: 'my_entity',
  attribute: 'blobAttribute',
  origName: 'img.jpg',
  filename: 'img.jpg',
  chunkSize: 10
})

Download file from server

For download file from server client call getDocument endpoint

  
      const UB = require(@unitybase/ub')
UB.App.blobStores.markRevisionAsPermanent({
  entity: 'my_entity',
  attribute: 'attributeOfTypeDocument',
  ID: 1000,
  revision: 2
})
  

  
      // convert base64 encoded string stored in `prm.signature` to binary and put to the store
docContent = App.blobStores.putContent({
  entity: 'iit_signature',
  attribute: 'signature',
  ID: ID,
  fileName: ID + '.p7s'
}, Buffer.from(prm.signature, 'base64'))