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 PdfWebControlLite instances. PdfWebControl instances do not rely on this architecture, see PdfWebControl Information Architecture.
It is important to understand the RAD PDF "Lite Document" and its naming conventions to ensure data security, proper operation, and maximum performance.
A RAD PDF Lite Document is an open PDF in a PdfWebControlLite instance.
RAD PDF Lite Documents are assigned a Session, 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 Lite Documents can be retrieved as a PDF, including all saved changes, edits, and additions.
Additionally, RAD PDF Lite Documents can be accessed using a DocumentKey, without disclosing or knowing its PdfLiteSession. There is an important distinction in RAD PDF between PdfLiteSessions and DocumentKeys
|RAD PDF PdfLiteSessions 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 PdfWebControlLite instance simultaneously. For example, calling LoadDocument(PdfLiteSession) using the same PdfLiteSession 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 PdfLiteSession) 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 PdfLiteSession for that user).|
PdfLiteSession vs DocumentKey
For new users, there is often some confusion between a PdfLiteSessions and DocumentKeys. The two are not interchangeable and represent two different approaches to accessing a given document.
- PdfLiteSession -
A PdfLiteSession is a unique, serializable class which represents a given document instance.
- PdfLiteSession classes must not be shared externally or provided to RAD PDF from an untrusted source.
- PdfLiteSession may be suitable for long term storage or association, but only if the LiteStorageProvider supports such (the default does NOT).
- PdfLiteSession can not be revoked.
Untrusted sources (e.g. a browser request) could possibly guess a PdfLiteSession which it should not be allowed to access.
PdfLiteSession objects are intended for trusted data sources (e.g. a secure server side database).
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 PdfLiteSession) is created when the CreateDocument or ImportDocument method of the PdfWebControlLite is called. LoadDocument loads existing documents, hence a new PdfLiteSession 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 PdfLiteSession objects, 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 PdfLiteSession.
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 ImportDocument method of the PdfWebControlLite is called.
By default, RAD PDF will use the ASP.NET Session State to maintain associations between the DocumentKeys and PdfLiteSessions.
Using a PdfIntegrationProvider, a custom PdfLiteSessionProvider can be implemented to use other methods to associate the two (e.g. a database).
Data stored in RAD PDF Lite Document is stored in a non relational manner.
Understanding the storage architecture is only important for advanced RAD PDF usage and implementing custom RAD PDF Lite Storage Providers.
By default, RAD PDF Lite Documents use the RAD PDF System Service and its built in storage mechanism to store data. This has one major caveat; the System Service is configured to remove data after it has not been accessed for some period of time (12 hours by default, see Admin Tool). A custom PdfLiteStorageProvider can be implemented to use an alternative storage provider like a database.
RAD PDF stores and retrives binary data from the PdfLiteStorageProvider. All data is associated with a PdfLiteSession and a subtype ID. The subtype ID is an int32 designating a data resource associated with a PdfLiteSession. A given PdfLiteSession will have multiple subtype records which need to be stored and retrieved.