PdfWebControlLite Information Architecture

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

Note
RAD PDF PdfLiteSessions 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 PdfWebControlLite instance simultaneously. For example, calling LoadDocument 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).

For new users, there is often some confusion between DocumentSessions (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 CopyDocument or CreateDocument or ImportDocument method of the PdfWebControlLite is called. LoadDocument(PdfLiteSession) 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.
  • DocumentKey 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).

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.