Skip to content

Managing Large Objects

Jump to bottom
Simon Mourier edited this page Feb 19, 2020 · 1 revision

Large objects such as pictures, video, or documents, can potentially weight hundreds of megabytes or even gigabytes; hence they can't be handled as a simple integer would be. They won't be stored the same way, nor they can be loaded and manipulated the same. In traditional fully hand-coded applications, handling large objects is a complex task which often proves to be tedious, and error prone; therefore, CodeModeler generates extra code to ease the developer in his task of managing large objects.

Large objects are commonly known as Binary Large Objects (BLOB), even though they can contain non-binary data. The blob acronym is the standard name and concept for such objects in programming, may it be in database programming or web development, and this is also the acronym used by CodeModeler to name the concept.

In the model you can declare large objects by setting the “Type Name” attribute of the desired property to blob (largebinary is also a valid value as an alias to the blob type). The following type names are available:

  • Blob (or largeBinary),

  • File (or attachment, document),

  • Film (or video),

  • Image (or picture, photo)

All those type names have the same result: a property of CodeModeler.Runtime.BinaryServices.BinaryLargeObject type in the Business Object Model (BOM).

For example, if we define the following model:

Managing Large Objects - Picture 321

The generated property Picture in the LargeFile entity is different from other properties. First, if you look at the generated table, you'll find that it didn't just generated one Picture column, but a set of columns enabling the developer to store extra information outside of the blob data itself:

Managing Large Objects - Picture 322

The same principle is observed in the BOM, you'll find the matching properties, each one of them being mapped to their corresponding generated column. Here is the default extra information available:

  • FileName (stored in a column named [EntityName]_[PropertyName]_FileName),

  • ContentType (stored in a column named [EntityName]_[PropertyName]_ContentType),

  • Attributes (stored in a column named [EntityName]_[PropertyName]_Attributes),

  • Size (stored in a column named [EntityName]_[PropertyName]_Size),

  • LastWriteTimeUtc (stored in a column named [EntityName]_[PropertyName]_LastWriteTimeUtc),

  • LastAccessTimeUtc (stored in a column named [EntityName]_[PropertyName]_LastAccessTimeUtc),

  • CreationTimeUtc (stored in a column named [EntityName]_[PropertyName]_CreationTimeUtc)

The fact that those metadata are stored outside of the large object itself is very important, since it allows the developer to load them without loading our large file.

Contrary to other standard properties, blob properties are not lazy loaded: they are not automatically loaded on the first use. Since they can trigger a potentially long loading time, they need to be loaded explicitly by calling the Load method on the blob property. In addition, those properties are not settable. All Create, Read, Update, Delete (CRUD) capabilities are located in the BinaryLargeObject class.

If you want to write to a blob property (save data from a file or bytes to the database) you need to use one of the Save methods provided. Here's a sample snippet to save and then load our Picture property of the LargeFile entity from a specified path:

// Saving picture to database
var file = new LargeFile();
file.Picture.FileName = path;
file.Picture.Save(path);
// Loading saved picture from database (and saves locally)
file.Picture.Load("test.jpg");
// Saving local picture to the database (from a local file)
file.Picture.Save("newtest.jpg");

Caching

Local blobs are automatically cached by default. In practice, when loading a blob property using the BOM, it actually loads it from the database the first time and stores it on the disk; consequently, next calls won’t load it back from database anymore, unless a modification was done on the blob which will reload it and update the cache.

By default, blobs are cached in a directory in the user profile corresponding to the user running the application. The default directory cache is located in the current logged-in user's profile: %localappdata%\Temp\CFBlobs. This can be configured at run-time through the configuration file of your application.

Memory Concerns

Keeping in mind memory usage is very important when working with blobs since they can potentially be very large files.

CodeModeler’s runtime never ever mounts the full blob into memory: its loading is streamed, and streams are used at each step of the process. However a ToArray() method returning a byte[] is available, if ever the developer wants to retrieve the complete large file in memory. It isn't best practice to use this method, and if ever it is used, please use it with care since performance and memory issues could occur.

When loading blobs prefer doing this:

// Loading saved picture in a PictureBox
using (var stream = file.Picture.GetInputStream())
{
   pictureBox.Image = new Bitmap(stream);
}

Rather than doing this:

// Loading saved picture in a PictureBox
using (var stream = new MemoryStream())
{
    file.Picture.Load(stream);
    pictureBox.Image = new Bitmap(stream);
}

Even if the second example is still better than using a byte[], we still allocate another stream: one more than the one CodeModeler used to load the binary large object. For this reason, you should always prefer the first sample to the second, because in the first one, the developer is reusing the loading stream, whereas the second sample loads the stream twice.

Clone this wiki locally