PdfWebControl Information Architecture
RAD PDF's architecture can be difficult to understand at first. This article aims to provide basic insight into its conventions. This article only applies to PdfWebControl instances. PdfWebControlLite instances do not rely on this architecture and do not use DocumentIDs, see PdfWebControlLite Information Architecture.
It is important to understand the RAD PDF "document" and its naming conventions to ensure data security, proper operation, and maximum performance.
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
RAD PDF DocumentIDs should not be exposed to or used from untrusted sources such as client browser requests. This is the purpose of DocumentKeys.
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).
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.
It is important to remember that in most cases, the ASP.NET View State is not a trusted source.
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.
A DocumentKey is automatically generated when the CreateDocument, LoadDocument, or CopyDocument method of the PdfWebControl is called.
Data stored in RAD PDF is accessed in a relational manner.
Understanding the storage architecture is only important for advanced RAD PDF usage and implementing custom RAD PDF Storage Providers.
RAD PDF data is primarily stored in 5 "tables":
The RAD PDF database differentiates between PDFs and Documents. The two are not interchangeable and represent two different containers of information, detailed below.
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.
PDFs are internal to RAD PDF and are not directly exposed by RAD PDF.
Documents are exposed by RAD PDF, most prominently as a RAD PDF Document.