RAD PDF's architecture can be difficult to understand at first. This article aims to provide basic insight into its conventions.

Document Architecture

It is important to understand the RAD PDF "document" and its naming conventions to ensure data security, proper operation, and maximum performance.

Overview

In general, a RAD PDF document is a open PDF in a PdfWebControl instance.

RAD PDF documents are assigned an ID, settings / permissions, a filename, and data describing changes made to the file since it was originally loaded from a PDF. When changes are made (server side or client side), the are saved to the applicable RAD PDF document. RAD PDF documents can be retrieved as a PDF, including all saved changes, edits, and additions.

Additionally, RAD PDF documents can be accessed using a DocumentKey, without disclosing or knowing its ID. There is an important distinction in RAD PDF between DocumentKeys and DocumentIDs

Note:

RAD PDF DocumentIDs should not be exposed to or used from untrusted sources such as client browser requests. This is the purpose of DocumentKeys.

Note:

At this time, a RAD PDF document is not intended to be opened in more than one PdfWebControl instance simultaneously. For example, calling LoadDocument(DocumentID) using the same DocumentID for multiple users at the same time is potentially problematic; changes made by one user may be overwritten or not seen by the other until a full page refresh occurs. If the same document (being loaded with the same DocumentID) is to be opened by two users simultaneously, it is recommended to create a copy of the document using CopyDocument instead of LoadDocument for one of the users (as this will create a new DocumentID for that user).

As explained below, documents are not the same as PDFs. The same PDF can be opened in as many PdfWebControl instances as you wish. For example, calling CreateDocument("filename", System.IO.File.ReadAllBytes(@"C:\demo.pdf")) for multiple users at the same time is not at all problematic (as each time this is called, the same PDF is loaded, but a new document and new DocumentID is created).

DocumentID vs DocumentKey

For new users, there is often some confusion between DocumentIDs and DocumentKeys. The two are not interchangeable and represent two different approaches to accessing a given document.

  • DocumentID - A DocumentID is a unique integer which represents a given document instance.
    • DocumentIDs must not be shared externally or provided to RAD PDF from an untrusted source.
    • DocumentIDs are suitable for long term storage or association.
    • DocumentIDs can not be revoked.

    Untrusted sources (e.g. a browser request) could easily guess a DocumentID which it should not be allowed to access.

    For example, if a user is viewing a document with DocumentID=2, the user might correctly guess that a document with DocumentID=1 exists. If your application trusts the browser to provide the proper DocumentID, the user can easily gain access to a document which does not belong to that user.

    DocumentIDs are intended for trusted data sources (e.g. a secure server side database).

    For example, if a user is associated with a document with DocumentID=2, your applicable may choose to store in its database that this user "owns" a document in RAD PDF with DocumentID=2. When the user returns to your web application, your application can simply use the LoadDocument method of the PdfWebControl to re-open the document for the user. The same should not be done with DocumentKeys because DocumentKeys can be revoked and do expire.

    Note:

    It is important to remember that in most cases, the ASP.NET View State is not a trusted source.

    Note:

    A new document (and hence new DocumentID) is created when the CreateDocument or CopyDocument method of the PdfWebControl is called. LoadDocument loads existing documents, hence a new DocumentID is not created.

  • DocumentKey - A DocumentKey is a unique access key (sometimes called token) for a given document instance.
    • DocumentKeys may be shared externally or provided to RAD PDF from an untrusted source.
    • DocumentKeys are not suitable for long term storage or association.
    • DocumentKeys can be revoked.

    Unlike DocumentIDs, DocumentKeys are generated using a secure, random method which can not be easily guessed.

    Similar to a session key, DocumentKeys expire. In RAD PDF, these keys expire at a fixed time after they are created. It is important that DocumentKeys expire (or are revoked) so that after a user has logged out or goes idle, another user at the same computer can not open that document using browser cache.

    Multiple DocumentKeys can correspond to a single DocumentID.

    DocumentKeys can be passed to a browser (via viewstate, querystring, cookie, etc) and later used to load a document in RAD PDF without concern.

    Note:

    A DocumentKey is automatically generated when the CreateDocument, LoadDocument, or CopyDocument method of the PdfWebControl is called.

Storage Architecture

See Also