ZipBrowser

This example shows two versions of a single application: The original version of
the application, in ZipBrowserBefore, and the polished version, in ZipBrowserAfter.

ZipBrowser is a simple document-based application used for perusing the contents of

a zip archive without having to unarchive it. The original version of the
application has three classes: a model class, ZipEntry, representing a single
entry in the zip archive; a view class, ZipEntryView, used to present a single
entry in the browser's preview column; and the NSDocument subclass, ZipDocument,
which serves as controller and as delegate to the browser.

Each ZipEntry stores certain minimal information about the entry: a path (the last
component of which is used as a name), a location in the archive, the original
uncompressed size, the size as stored compressed, the compression type, and a CRC.
There is an implicit tree structure to the entries in an archive, based on the
paths stored in the zip archive name fields, which is used to store directory
hierarchies. This is represented by having two types of ZipEntry, leaf and non-
leaf, with the non-leaf entries having an array of child entries.

The ZipEntryView displays a small subset of this information: an icon from

NSWorkspace representing the entry, the name, and the two sizes. It draws the icon
using standard NSImage methods, and it lays out and draws the strings using
standard NSStringDrawing methods.

The ZipDocument class reads in the contents of an archive as a tree of ZipEntry

instances, starting from a root instance. One notable feature is that it uses the
item-based NSBrowser API introduced in Mac OS X 10.6, which greatly simplifies the
task of acting as an NSBrowser delegate.

Differences Between ZipBrowserBefore and ZipBrowserAfter

The modifications between ZipBrowserBefore and ZipBrowserAfter fall into six

categories: 64-bit readiness, performance and responsiveness, security,
localization and internationalization, usability, and accessibility. The 64-bit
readiness changes consist primarily of changing the types of various integers from
unsigned or int to something more appropriate: NSUInteger or NSInteger for those
that represent types used with Cocoa interfaces, and uint32_t or uint16_t for those
that represent specifically sized values taken from the zip archive data format.

The performance and responsiveness changes consist of (a) adding a FileBuffer class
for file access, and (b) placing most access to this class into the background
using an NSOperationQueue. The FileBuffer class represents a simple wrapper around
NSFileHandle, adding some buffering and byte swapping (the zip format is little-
endian). It is deliberately not thread-safe; instead, the application serializes
it by assigning a single instance to a single-threaded NSOperationQueue. The
ZipDocument instance creates the FileBuffer for a given document, and uses it only
long enough to obtain some basic information and confirm that the file does indeed
look like a zip archive; after that, all access to the FileBuffer goes through the
ZipDocument's NSOperationQueue. An operation is created that calls a specific
ZipDocument method to read the entries, put them on a queue, and periodically send
the collected ZipEntry objects back to the main thread to be added to the document
and the user interface. In addition, NSDocument's concurrent document opening is
turned on, to make opening of multiple documents concurrent with respect to each
other.

The security changes consist of adding checks at each point that a value is read
from the zip archive, to make sure that the value is intelligible and in range.
All offsets within the file are compared both above and below to make sure that
they are reasonable, to make sure that they are not made invalid by arithmetic
overflow.

The localization and internationalization changes consist of making all static

strings into entries in the Localizable.strings file, using an NSNumberFormatter
for formatting displayed numbers, and significantly improving the encoding support
for reading names from the zip archive entries. Zip archive entry names were
originally DOS Latin US / IBM code page 437, but this was not really specified, and
in practice names have simply been strings of bytes. Mac OS X uses UTF-8, as do a
number of recent zip usages; there is now a bit that can be (but isn't always) used
to specify UTF-8. To handle a variety of possible encodings, ZipBrowserAfter uses
a single main document encoding (default UTF-8), followed by several fallbacks.
There is also a reopenWithEncoding: method and corresponding menu items; each such
menu item specifies an NSStringEncoding as its tag, and causes the document to be
re-read with the specified encoding as the new main document encoding.

The usability changes consist of adding drag support both in the browser and in the
preview view. Three pasteboard flavors are used: file promises, for drags to
Finder; filenames, for drags to other attachment-handling applications such as
TextEdit; and strings, for everything else. Creation of the dragged file is always
done lazily. Furthermore, since FileBuffer operations are defined to be on the
NSOperationQueue, an operation is created to do this, which calls back to the
ZipDocument to read and uncompress the entry and write it to disk. Currently the
drag code waits for the background file operation to complete, so an error can be
presented immediately if necessary, but this is not essential.

The accessibility changes consist of adding an AccessibilityElement class to

represent each of the elements in the ZipEntryView (one image and three strings)
for accessibility purposes. These are created lazily on demand when accessibility
is in use, and they are assigned the contents and bounds of the corresponding
elements.

There are some things that this example does not do, that are left as exercises to
the reader. For example, none of the possible filesystem attributes (permissions,
etc.) that can potentially be stored in the archive are handled; the drag code
retrieves the contents of the entry and nothing else. Double-clicking on entries
is not supported; it might be possible to add support so that this would unarchive
and open that specific entry. More generally, this example serves only as a
viewer, not as an editor; no support is added for dragging files into an archive or
otherwise modifying it in any way.

Changes from Previous Versions

Updated to latest Snow Leopard API, and updated Xcode project and Interface Builder
file formats.

Feedback and Bug Reports

Please send all feedback about this sample by connecting to the Contact ADC page.
Please submit any bug reports about this sample to the Bug Reporting
<http://developer.apple.com/bugreporter> page.

Copyright (C) 2008-2009 Apple Inc. All rights reserved.