PdfWebControl Information Architecture

In general, a RAD PDF document is an 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 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).

For new users, there is often some confusion between DocumentIDs and DocumentKey. 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 CopyDocument or CreateDocument or ImportDocument method of the PdfWebControl is called. LoadDocument(Int32) loads existing documents, hence a new DocumentID is not created.

• DocumentKey - A DocumentKey is a unique access key (sometimes called a 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.

RAD PDF data is primarily stored in 5 "tables":

• keys - Keys which reference Documents in the docs "table". Multiple Keys can reference the same Document.
• docs - Documents which reference PDFs in the pdfs "table". Multiple Documents can reference the same PDF.
• objs - Object data referenced by a document instance in the docs "table". A single Document can have multiple objects.
• pdfs - PDFs which reference Pages in the pges "table".
• pges - Pages rendered.

The RAD PDF database differentiates between PDFs and Documents. The two are not interchangeable and represent two different containers of information, detailed below.

• PDF (pdfs) - A PDF constitutes a file, as loaded into RAD PDF. PDF files are preserved in RAD PDF as a "starting point" or "template" for a Document instance.

  Note
  If the AllowFindMatchingPDF property of the PdfWebControl is set to true (default), RAD PDF will automatically look for an identical, already loaded PDF in the pdfs "table" in attempt to be more efficient.

  Note
  PDFs are internal to RAD PDF and are not directly exposed by RAD PDF.

• Document (docs) - A Document constitutes an instance of a PDF. This allows multiple users to use the same PDF as a "starting point" for different Document instances without affecting each other.

  Note
  Documents are exposed by RAD PDF, most prominently as a RAD PDF Document.