HOWTO: Using Scratch Space From Your Java Applet

ID: Q172200

The information in this article applies to:

Microsoft SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

This article describes how to access scratch space on a client machine from a Java applet. Scratch space requires features of Internet Explorer (IE) and the Microsoft virtual machine. These features are available in Internet Explorer 4.0 and the Microsoft virtual machine that includes Build 2252 or later.

MORE INFORMATION

What is Scratch Space?

Scratch space is storage on the client machine that an applet can safely access without needing full access to the client file system. Scratch space is managed by the Microsoft virtual machine to ensure that it cannot be abused by malicious applets.

The following is true of scratch space:

Persists across applet invocations and download sites. Applets with the same signer downloaded from multiple sites have access to one unified scratch space. This is ideal for storing configuration information for applets that may be used in many places.

Is allowed in most IE Security Zones by default. The user will generally not be asked if using scratch space is okay.

Is available only to the signer of the applet that created it.

Is safe. Access is restricted to a certain portion of the client directory structure. Applets cannot use scratch space to modify files outside the allowed scratch space area.

Is secure. Applets must be signed or run in a fully trusted zone to use scratch space. Unsigned applets run from a fully trusted zone or from the classpath have their own scratch space.

Is limited to a fixed amount of disk space. Applets may request more space before the applet starts running, but the user must approve these requests.

Can be allowed or denied by the security system separately from regular file operations.

How to Use Scratch Space in Your Applet

Follow these steps to use scratch space in your applet:

Import the Microsoft Client Storage library by placing the following line at the top of the file that will use scratch space:
```
import com.ms.io.clientstorage.*; 
```

Declare a variable of type ClientStore to provide access to the storage system:
```
ClientStore m_store; 
```

Retrieve the Client Store object from the system client storage manager. This action could throw an IOException:
```
m_store = ClientStorageManager.getStore(); 
```

Create an input or output stream. This could also throw an IOException:


OutputStream o = m_store.openWritable(m_filename);
InputStream o = m_store.openReadable(m_filename);

Access the stream as you would any other stream.

Scratch space will work from your local machine for debugging, but for use on the Internet, place the compiled class into a CAB:
```
cabarc N MyApplet.cab MyApplet.class 
```

Sign the cab with privilege information that requests client storage access. For Internet Explorer 4.0 Preview 2, this means signing at either the Medium or Low level.
```
SignCode ... -j JavaSign.dll -jp Medium ... MyApplet.cab 
```

Variations:

You can also open an output file where new data is appended onto the existing file. To do so, call the following:


ClientStore.OpenWritable(String filename, boolean append) throws IOException;

If append is true, new data will be appended. Otherwise, the file will be truncated if it already exists. In either case, the file is created if it does not already exist.

If all you need to do is open a file for input or output, you can do so without having to declare a ClientStore variable. Simply call one of the following three functions directly. These three functions maintain the store internally. Each function throws an IOException in the case of an error.


InputStream ClientStorageManager.OpenReadable(String filename);
OutputStream ClientStorageManager.OpenWritable(String filename);
OutputStream ClientStorageManager.OpenWritable(String filename,
                                            boolean append);

Example

The following code fragment opens a scratch space file called "Demo.txt" on the client machine, and appends a string to the file:


m_store = ClientStorageManager.getStore();
OutputStream os = m_store.openWritable("demo.txt", true);
os.write("This is stored in scratch space");

REFERENCES

More information on the clientstorage package is available in the following location:

For additional information on making your Java Code trusted in Microsoft Internet Explorer, please refer to the following Knowledge Base article:

Q193877 HOWTO: Making your Java Code Trusted in Internet Explorer

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/

http://support.microsoft.com/support/java/

Additional query words:


Keywords          : kbnokeyword kbCommandLine kbSDKJava300 kbVJ kbSDKJava310 IOPkg JVM kbSDKJava320 
Version           : WINDOWS:2.0,2.01,2.02,3.0,3.1,3.2
Platform          : WINDOWS 
Issue type        : kbhowto

Last Reviewed: July 27, 1999