SilverDox client is using part retrievers (a class deriving from the interface IPartRetriever) to access remote or local files. The role of a part retriever is to make required parts of the document available to the Silverlight viewer. The following part retrievers are available out of the box:

1.       LocalPartRetriever, which is typically used to retrieve documents from the local file system. This part retriever is constructed using a seekable Stream, such as a FileStream. Note, however, that any seekable Stream (e.g. a MemoryStream) can be used, expanding the number of scenarios in which this retriever could be used.

2.       HttpPartRetriever which is used to retrieve a Silverlight files from an HTTP server that supports byte-serving. Byte serving allows the retriever to transfer arbitrary parts of the file, allowing whatever page is visible to be transferred before other pages that have not yet been transferred. This is the preferred part retriever when requesting previously-converted documents from a web server.

3.       HttpStreamingPartRetriever which is used to retrieve a document from an HTTP server that does not support byte-serving, or optionally when the document is converted to Silverlight XPS (XOD) on demand. This retriever transfers the entire document in order from beginning to end, with pages and thumbnails displayed as each page arrives.

The following section describes how to choose between an HttpPartRetriever and an HttpStreamingPartRetriever.

As stated above, the HttpPartRetreiver must be used in conjunction with a web server that supports byte-serving (http://en.wikipedia.org/wiki/Byte_serving). Byte-serving is used to transfer a file from a server to client in an out-of-order fashion, i.e. the middle or end of the file can be transferred before the beginning. This is a useful feature in SilverDox because when a user scrolls to an unloaded page of a partially loaded document, the page’s content can be prioritized and immediately transferred, allowing near instant viewing of the page without waiting for intervening pages to load. If the converted Silverlight document is available when the document is requested, and the web server supports byte-serving, the HttpPartRetriever will give the best user experience and optimal performance. HttpStreamingPartRetriever is designed to be used in situations when a remote web server does not support byte-serving or if the document must be converted on-demand. There are situations when even though the HTTP server supports byte-serving, the HttpStreamingPartRetriever is the preferred part retriever. For example:

·         The HttpStreamingPartRetriever may provide a better user experience in the case that documents are converted on demand. This is because converting large documents can require some time, and having the client wait until the conversion process is complete (so that the document can be byte-served) is undesirable. In this scenario, the HttpStreamingPartRetriever is the better choice because it can begin to transfer the document to the client when the conversion process begins. This allows the client to see results very quickly and for the document to be converted and transferred concurrently.

·         The HttpStreamingPartRetriever may be required when the document is only available via a URL with dynamic content, because most web servers do not support byte-serving in this situation. This could be the case if the documents are stored in a database, and the documents cannot be temporarily written to the file system and assigned a static URL.

See the decision tree below to help in deciding which part retriever to use.

A part retriever has three properties which control how a Document object and DocumentViewer object will load and display Silverlight document (i.e. a XOD file). Below is the API documentation for each property, and a table stating the default value for each part retriever and why that value is usually (or always) the best choice for that retriever.

Property: bool BackgroundLoadDocument { get; set; }

Description: Gets or sets whether the Document will continue to load in the background during idle periods.

Remarks: Background loading is only useful for HttpPartRetriever. HttpStreamingPartRetriever inherently loads all resources, and LocalPartRetriever is sufficiently fast that background loading provides no advantage.

Property: bool ShowThumbnailBeforePageContent { get; set; }

Description: Gets or sets whether the viewer will display an enlarged thumbnail of a document's page when the page is scrolled to but has not yet been loaded.

Remarks: Showing an enlarged thumbnail on a full page before the content is available is useful for HttpPartRetriever because the time to acquire the entire page content can be noticeable, but the time to acquire a thumbnail is minimal. LocalPartRetriever does not need to show a thumbnail first because the entire page content can be quickly retrieved, and HttpStreamingPartRetriever loads page content before any thumbnails, so it is not possible to show a thumbnail first.

Property: bool UseDocumentThumbnailIfAvailable { get; set; }

Description: Gets or sets whether the method Document.LoadThumbnailAsync() will use pre-generated page thumbnails (if they are available in the document), or will create thumbnail created from the page contents.

Remarks: If a document contains pre-rendered thumbnails, the viewer has the option to use them, or alernatively, to generate thumbnails internally by rendering and scaling the page content. Using the built-in thumbnails is preferred except for the case of HttpStreamingPartRetriever, when it is faster to display internally generated thumbnails.

Table 1: Default values for a Part Retriever’s properties which affect how a Document is loaded, and how a DocumentViewer displays it.