Multistep saving

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.3
  • Enterprise
  • Community
  • Planned

Overview

Uploading files

Sense/Net ECMS is capable of storing large files in the Content Repository. But before we can index these files or create preview images for them, we need to upload them to the repository. This can be relatively slow and it is important to know the characteristics of this process when dealing with large files. This article is for developers and portal builders who want to know more about handling huge files or create a saving process that separates metadata and binary information.

Why do we need multistep save?

There are a couple of reasons why we designed the saving process this way:

  • content life cycle events: the events of content creation and modification must be fired at the correct point of the content life cycle and only then. For example in case of a large file the created event should not be fired at the start when only the metadata are saved to the repository, but only when the full binary is uploaded.
  • prevent content modification: during a long-running upload process the content needs to be locked and must not be modified. We need to protect the content from any kind of modification during this process.

A multistep save operation is closely related to uploading binaries. No metadata modification can be made on the content during file upload. Even the owner user is not allowed to modify the content during the process.

Upload

When a file is big enough to be uploaded in chunks, the upload action starts a multistep save in the background. This means the new version will be accessible only to the owner and the content will be locked to him. Creating or modifying event will be fired (depending on whether the content is new or not) and the chunks will start to flow to the database.

During the operation previous versions of the content are still accessible. When other users try to download a file during a multistep save, they will receive the last version of the binary that is accessible to them (previous minor or major).

When the process ends, the corresponding created/modified event is fired and the content is released (checked in in the background). Of course checkin happens only if the content was not checked out before.

If the content was checked out at the beginning of a long-running (multistep) save operation, it will remain checked out after the operation ends and modified event will not be fired at the end.

If the file is small enough to be uploaded in one chunk, a regular save will be initiated and all metadata and binary data will be saved in one round. The whole process is automatic and hidden under the hood of the built-in Upload action.

Starting multistep save manually

There are cases when you need to start the multistep saving process manually. For example you want to allow your users to fill in a form with metadata, create the content using that data and upload the binary after. Or you have to allow uploading multiple binaries to different binary fields of the same content. And you want the created/modified events to be fired only once, at the end of the whole process.

Source code

To initiate a multistep saving process from source code you only have to call a different overload of the Save method on the content:

var content = Content.CreateNew("File", parentFolder);
content.Save(SavingMode.StartMultistepSave);

The above code line saves all fields of the content and puts it to a creating/modifying state, depending on whether it was new or not.

Saving state

You can check the current state of the content by using the SavingState property on the content handler:

if (uploadedContent.ContentHandler.SavingState != ContentSavingState.Finalized)
{
	...
}

The possible values of the property are the following:

  • Finalized: the content is fully accessible (most content are in this state)
  • Creating: creation process started
  • Modifying: modification process started
  • ModifyingLocked: modification process of an already locked content started

OData

To initiate a multistep saving process from the client side you can send a regular OData request (POST, PUT or PATCH) as you would normally. You only have to specify a special URL parameter:

Create a file under a document library with the name sampledocument.docx and fill it’s Index field with 10.

$.ajax({
    url: "/OData.svc/workspaces/Project/budapestprojectworkspace('Document_Library')?multistepsave=true",
    dataType: "json",
    type: 'POST',
    data: "models=[" + JSON.stringify({ '__ContentType':'File' , 'Name': 'sampledocument.docx', 'Index': 10 }) + "]",
    success: function () {
        console.log('Content is successfully created');
    }
});

Writing binary chunks

The only thing you can do during a multistep save operation is to fill a binary field of a content (usually a file). You may do this either on the server or from the client side.

Source code

On the serve side please use the Chunk save API to write binary chunks to the database.

OData

To upload binary chunks from the client side, use the Upload action.

Finalizing the save process

If you started a multistep saving process than you are responsible for finalizing it. If you use the built-in Upload action for sending the binary chunks, it will behave differently at the end: it will not finalize the content for you.

As you can see in the sections below, you can end the process either from source code or from the client side through OData.

If you do not call the FinalizeContent method explicitely, the content will remain in creating or modifying state and users will see only the previous version.

Source code

To finalize a content from source code you can call the following method:

uploadedContent.FinalizeContent();

The method above will thrown an exception if the content is already finalized.

OData

You can finalize a content by calling the Finalize content OData action. See an example in that article.

Related links

References

There are no related external articles for this article.