Cramfull Compiled Resources: overview
The Cramfull Compiled Resources library compiles any kind of resource into a standard Java class file.

See:
Description

Packages

be.arci.cramfull	The Cramfull Compiled Resources library enables to distribute resources for Java applications in compiled form, with internationalization support.
be.arci.pub	Supplies some example implementations and utilities for the Cramfull Compiled Resources library, together with their source code.

Cramfull Compiled Resources: overview

The Cramfull Compiled Resources library compiles any kind of resource into a standard Java class file.

Contents

1. Introduction
2. Benefits
3. QUICK START
4. Evaluation version

Introduction

1. What are resources?

   Computer programs operate on data. Often data is external to the program, and some type of data is even prepared using other pieces of software, like image editors. Such data, which is mostly read-only to the application program, is known as resources.

   Resources include icons, cursors, text, menus, dialog boxes, audio clips, animation clips, etc. Resource are also commonly used to separate national language data from the program logic, so that different languages can be plugged in by supplying the appropriate resource. It is obvious that in today's advanced multimedia user interfaces, resources are vital portions of attractive applications.

2. Distributing resources

   Because of their static and external nature, resources, and the resource files in which resources are typically contained, are treated separately and differently from other types of data. Different programming environments propose different solutions for distributing resources with the application, and for accessing them at runtime, often by bundling them in the same file as the executable program.

3. Resources and Java

   Java has no such provisions for bundling resources. Java runs under different operating systems, each with their own file naming conventions and restrictions. Java Applets even have no access to a file concept, but have to retrieve their resources through URL-s. Some webservers (and some browsers) do not transmit every type of resource data correctly, or not at all.

   To complicate matters further, Java applications are often distributes in zip-files, compressed or uncompressed, or in jar files. Resources can be packaged in these archives together with the application, or kept apart on the (server) file system for not having to load all language resources at once, when only one is needed. Also several Java Virtual Machines have limited support for one or more of these archive types.

4. One solution

   For all these reasons, a Java programmer has to make assumptions before he starts programming. Assumptions about how and on which platform his application will be distributed. If these circumstances change, he will often have to modify and retest his code.

   The Cramfull Compiled Resources library offers a standard way of packaging, distributing and accessing resources that works in all environments. Therefor there is only one decision left to make about how to distribute your resources: use Cramfull!

   The Cramfull Compiled Resources library improves on the concept of a Java resource class. A Java resource class is an ordinary Java class containing encapsulated resources like properties files, images, sounds, menus, etc. Java resource classes have several valuable attributes to a Java programmer. In particular, a Java resource class can be used for internationalizing Java based programs, allowing application independent interchange of strings, sounds and images. Java resource classes can also be loaded by opening just 1 URLConnection, dramatically improving the performance of loading many small static resources.

Benefits

The Cramfull Compiled Resources library enables you to distribute resources for Java applications in compiled form, as Java classes that are subclasses of java.util.ResourceBundle. The benefits of the Cramfull approach are:

Compatibility

Our Cramfull classes rigorously follow the Java class-file format standard, without adding any attributes or special flavours. And what with all these different runtime environments? If there is anything they can load, it will be the Java classes. So with Cramfull classes you play on the safe side.

Distribution comfort

More than 10.000 resources of any kind can be packaged into one Cramfull class-file. You can easily administer the resources to be compiled into multiple Cramfull classes through a single text-format command file.

Download speed

Bundling many small resources into a single standard Java class-file has the same download speed advantages as bundling them into a .zip or .jar file, but without the worries for lacking support in older or ill-featured Java Virtual Machines (JVM). Uploading many resources to a website is obsolete: only a single class-file is needed, probably packaged with the other classes of the application.

Synchronous availability

Once the Cramfull class is loaded by the JVM, all resources in it are available synchronously. You can even overcome the very short decoding delay by using the caching capabilities of the Cramfull class. Here comes smooth animation and immediate sound feedback, without writing extra code to preload resources. You can also forget about image strips and their pixel measurements.

Any type of resource

The Cramfull Compiled Resources library stores any type of resource that can be expressed in bytes. The default resource compiler supports all file-based resources; this includes Java Objects that are serialized to file in advance. An extended resource compiler example also shows how to serialize Objects directly to a Cramfull class.

Internationalization (I18N) support

The Cramfull Compiled Resources library now makes it very easy (only 1 Java statement!) to load default resources of any kind to supplement resources per language and/or country. Think of recorded speech sound files, or images containing text, in the appropriate language. Or flags and other national symbols. Even advanced uses like tayloring your application's properties according to different national rules or regulations are now trivial. Without the Cramfull Compiled Resources library, you would have to do circumstantial coding and keep track of directory trees per locale when distributing your application.

QUICK START

The Cramfull Compiled Resources library contains lots of functionality to tailor it to your needs. However, to start programming, you only need to know of a limited number of classes.

We suggest you read the following first:

1. Cramfull
   API for your application program to retrieve resources from Cramfull classes.

   ResourceCompiler

   commandline utility to compile resource files into a Cramfull class-file.

   SerializingResourceCompiler

   extension of ResourceCompiler that also compiles serializable Objects into a Cramfull class-file.

   ResourceViewer

   applet and commandline utility to review the resources you just compiled into a Cramfull class-file.

   be.arci.cramfull

   package description about the classes you need to include with your application distribution.

All other classes are either supporting classes you need not interface with, or advanced API's for special uses.

Evaluation version

The evaluation version of Cramfull has some restrictions, to make unlicensed use in commercial environments less attractive. We do hope applicants licensees falling under one of the free license types are not hindered too much by these restrictions. These are the restrictions:

evaluation version	production version
Encoded resources are always compiled into the Cramfull subclass itself, and thus stay in memory as long as the Cramfull subclass is loaded.	Encoded resources can be placed in a nested class, that can be garbage collected as soon as the Cramfull subclass is initialized.
No single resource can be larger than about 285 kBytes original filesize (depending on the nature of the data and the encoding that is used).	There is only a physical limit imposed by the class file format: the combined original file size of all resources compiled into a class cannot exceed circa 1.790 MByte; there is no individual file size limit.
A Cramfull class cannot contain more than about 100 resources.	There is only a physical limit, imposed by the class-file format. We have successfully compiled sets of more than 10.000 resources.
The Cramfull class can manage some 500 resources during 1 JVM session in total.	There is no such restriction.