Subsetting the MacBinary Toolkit 2 for Java

Last revised: 14May2003 GLG

This document provides general guidance about subsetting the MacBinary Toolkit 2 for Java. It is not a complete detailed guide, and determining an absolute minimum subset requires you to determine for yourself which components and capabilities can be omitted for your particular needs.

Under the Artistic License, Section 4 allows you to redistribute compiled "executable" versions of the Standard Version that omit any components you wish, as long as you provide a pointer (e.g. a URL) in your program or documentation to where the full Standard Version may be obtained. You must provide the same pointer whether you distribute a full set of "executables" or only a subset. In the case of the MacBinary Toolkit, "executables" means the compiled Java classes and or JNI-library, in whatever form (JAR, ZIP, separate files, etc.).

Subsetting

The simplest way to guide you through subsetting is to describe a sequence of successively smaller subsets that provide successively fewer capabilities. You can create these subsets by omitting certain sections along the following lines:

1. Omit all of the "app.test.*" package tree if you don't need any of the test cases. If you want to use some capabilities, such as parts of the ReplicatorFrame, you can extract the relevant source into a new class, which you must make available in source form as a derivative work.

2. In addition, omit all of the "app.macbinary.convert" & "app.macbinary.spy" packages if you don't need the AWT demo apps. Again, if you need some of their capabilities, you can extract the relevant source into a new class, which you must make available in source form as a derivative work.

3. In addition, omit as many of the "app.macbinary.cmd" classes as appropriate..

4. If you don't need any of the apps or AWT support at all, omit all of the "app.*" package-tree, including "app.util". If you need selected classes, such as app.util.Fixes but nothing else, omit everything but the selected classes. After omitting everything in the "app.*" package-tree, there are no other uses of AWT anywhere else in the MacBinary Toolkit. You may find this useful when targeting platforms that do not have AWT.

5. If you aren't doing any actual MacBinary encoding or decoding. omit all of "glguerin.macbinary". You can omit the entire package if you only need to read resource-forks or access the core I/O capabilities. You can also selectively include only certain classes from "glguerin.macbinary", such as if you only need a MacBinaryReceiver to act as a decoder, but don't need any encoding capability. You'll have to perform this fine-grained selection for yourself.

6. If you aren't using any of the classes of "glguerin.iox", omit them. Or omit only the ones you're not using.

7. In addition, omit any I/O implementations under "glguerin.io.imp.*" as desired. All the Mac OS implementations (jd1, jd2, ten, and macosx) use classes in "glguerin.io.imp.mac.*", so if you use any of those implementations you'll need their base classes. If you omit implementations, be sure that you reset and reinitialize the PathnameFormat mappings, along with the MacPlatform factory bindings, to properly reflect your omissions. You won't have to edit those classes -- just clear out the standard defaults and establish your own values when your program starts up. Both PathnameFormat and MacPlatform have APIs for this.

Going farther than the above subsets will require careful dependency analysis and selection of classes. You might end up saving a couple of KB overall, but you have to decide for yourself whether it's really worth it, and then extensively test the selected subset you've made.

Isolated Inclusion

Some classes in the MacBinary Toolkit are useful in isolation. This section is a guide to some of the more plausibly extractable classes or methods.

• app.util.AppXXX classes -- These AWT-based classes make it relatively easy to write new single-Frame utility programs. The various demos and test-cases illustrate how.

• app.util.Hex -- Format data in hex.

• app.util.Settings -- A flexible extension to java.util.Properties that makes it easier to find and load properties files, including loading them from a JAR resource.

• glguerin.io.AccentComposer -- Mac OS 9 and Mac OS X both return filenames that have combining accents rather than composite accented characters. This can sometimes be a pain to work with. AccentComposer relies on no other classes, so is easily reused in isolation.

• glguerin.io.Pathname and PathnameFormat -- Very useful if you have some non-trivial pathname manipulation to do. These classes depend on each other. Some of the PathnameFormat subclasses (class names starting with "PF_") depend on AccentComposer, but you can omit those subclasses if you must (note: requires minor source changes).

• glguerin.io.RandomRW and subclasses -- This abstract class and its subclasses may be useful if you need more features or capabilities than java.io.RandomAccessFile can provide. There are also some additional RandomRW subclasses in the glguerin.iox package that are easily isolated and reused.

• glguerin.iox.UTF8 -- More flexible than the UTF-8 support in DataOutputStream and DataInputStream. UTF8 relies on no other classes, so is easily reused in isolation.

• glguerin.util.Arrayer -- Simplifies making variable-length arrays of general or specific types. Much simpler than Vector, and no synchronization overhead.

• glguerin.util.Implicator -- A building-block to make platform-sensing and implementation-selecting facilities. See the source of MacPlatform for an example. The nested Implicator.Chain class uses an Arrayer.

To Greg's Home Page
To Greg's Software Page