Main Page Cookbook/Overview ImageMeister the jcprops file Licensing Please Vote! Binary Installation & Configuration [ Win · Mac · Nix · OSX ] Changes Public API Source Code Main Page Java [ Common · Win · Mac · Nix ] Native Code [ Common · Win · Mac · Nix ] Manifest Native Code Overviews [ Common · Win · Mac · Nix · Strings ] Macros [ General · Native Macros ] Walkthroughs [ Java only · Java and native ] Building [ Win · Mac · Nix · OSX ] Distribution Issues

## JConfig Overview

This document contains a general overview of the various capabilities of JConfig. See the sample applications for specific examples of the use of these features. See the package documentation for details on specific classes.

- Initializing JConfig
- Working with Files
  - Enumerating the user's hard drives
  - Enumerating the contents of drives and directories
  - Converting from java.io.File objects to JConfig DiskObject objects
  - Get information on drives, directories, and files
  - Get settings for files
  - Working with aliases
  - Working with file systems
- Working with Web Browsers
  - Launching a URL or file
- Working with Video Monitors
  - Enumerating the user's monitors
  - Getting monitor information
- Working with External Processes
  - Finding Applications
  - Converting a java.io.File into a JConfig AppFile object
  - Creating processes
  - Sending messages to processes
  - Getting Information on processes
- Working with File Types
  - Converting between Mac and Windows
  - Getting the file type of a file
  - Getting the file types associated with an application
- Customizing JConfig
  - jconfig.cfg
  - jcfactrz.txt
- Unimplemented Features

## Initializing JConfig

To use JConfig, you must make sure that JConfig can find the files it needs, and you must initialize JConfig correctly. If you have a problem with JConfig setup, please read the following, and look through the JConfig batch files and the sample programs for examples of how to initialize JConfig. The sample programs are in the `source/com/tolstoy/testjc` folder.

JConfig uses the following files:

- JConfig.zip (used on all platforms) - contains the .class files for all platforms

- jconfig.cfg, jcfactrz.txt, jcprops.txt (used on all platforms) - these contain configuration information, and will be referred to as the support files

- jcnfigSN.dll, jcnfigSW.dll, etc. (used on Windows only) - the Windows DLLs

- JConfig.shlb (used on Mac only) - the Mac shared library

- libjconfiglx0.so (used on Linux only) - the Linux shared library

The 'Manifest' section of readme.html lists the location of each of these files in this distribution.

Using JConfig consists of three basic steps:

- Make sure that JConfig.zip is in the classpath. You can do this using a batch file on Windows, using a shell script on Unix, or using the JBindery app on Mac...

- Make sure that JConfig can find its native code libraries. You can do this using a batch file on Windows, using a shell script on Unix, or by putting JConfig.shlb in the shared library search path on Mac...

- Call the FileRegistry.initialize() method with a File object representing the directory which contains the support files (jconfig.cfg and jcfactrz.txt).

Assuming that the support files are stored in the folder containing your app, one way to call FileRegistry.initialize() is:

        curDir = new File( System.getProperty( "user.dir" ) );
        FileRegistry.initialize( curDir, 0 );

NOTE: The directory you pass to FileRegistry.initialize() must be writable; JConfig will create temporary files in this directory, but will delete them when they are no longer needed. A future version of JConfig may also create configuration files in this directory.

NOTE: the second argument to FileRegistry.initialize() is not currently used.

Additional platform-specific information, including instructions for setting the path and classpath, is provided in the following files:

- wininfo.html (Windows)
- macinfo.html (Mac)
- nixinfo.html (Unix/Linux)
- osxinfo.html (OSX)

If the directory passed to FileRegistry.initialize() does not contain both of the support files, JConfig will use default values, which are stored internally. However, don't rely on this behavior: make sure that the directory contains both these files. If JConfig can't find either of these files, a warning will be printed to System.out, indicating which file couldn't be found.

> If this occurs, check that the directory passed to FileRegistry.initialize() contains both these files. The file 'Tester.java', in the `source/com/tolstoy/testjc` folder, contains a 'doubleCheckJConfigInitializationDirectory()' method which you can use to check whether a folder contains 'jconfig.cfg' and 'jcfactrz.txt'.

If both the support files can be found, and your app is running on a supported VM, JConfig will initialize correctly provided that it can find its native code libraries.

However, if it can't find its native code libraries, only a limited set of functionality will be provided. In this case, JConfig will output a message saying that FileRegistryPlain has been loaded.

> In this case, make sure that the appropriate native code library is in the path, using the instructions in wininfo.html (Windows), macinfo.html (Mac), nixinfo.html (Unix/Linux), or osxinfo.html (OSX)

More Details:
Depending on how it's initialized and what platform it's running on, JConfig has three modes of operation:

- full mode: all FileRegistry methods work as expected
- fallback mode: some FileRegistry methods work; most return null or -1
- error mode: all FileRegistry methods return null or -1

For JConfig to enter 'full' mode, all of these must be true:

- JConfig must be running on one of the supported platforms
- JConfig must be initialized with the directory containing both 'jconfig.cfg' and 'jcfactrz.txt', and this directory must be writable.
- If this platform uses native code, JConfig must be able to find the native code.

If JConfig is initialized correctly, and it can find all the files it needs, it will be in 'full' mode on supported platforms, and in 'fallback' mode on unsupported platforms.

Note that JConfig currently supports the MRJ and CodeWarrior VMs on PowerMac, the SunJDK1.x and MS VMs on Win95/Win98/WinNT, and most, if not all, Unix systems.

## Working with Files

JConfig lets you obtain extended information on drives, directories, and files, as well as letting you enumerate the contents of drives and directories. In JConfig, all objects which represent drives, directories, files, and aliases implement the DiskObject interface. The class hierarchy for these objects is as follows:

    DiskObject
    	DiskVolume ( represents drives )
    	DiskFile ( represents directories and files )
    	    DiskAlias - represents aliases

There are several ways to obtain these objects, as described below.

Enumerating the user's hard drives

The FileRegistry.getVolumes() method returns an array containing each of the user's currently mounted hard drives. You can then get information on each drive, and enumerate their contents.

Enumerating the contents of drives and directories

Objects which implement the DiskObject interface have the 'iterate' method, which lets you enumerate the contents of the object. Of course, this only has meaning for drives and directories.

To use this method, you create an object which implements the DiskFilter interface, and pass it to the DiskObject's 'iterate()' method. The DiskFilter's visit() method will be called with a DiskObject which represents each item contained within the containing object.

Converting from java.io.File objects to JConfig DiskObject objects

The FileRegistry.createDiskObject() method takes a java.io.File object, and returns an object which implements the DiskObject interface. The returned object may also implement the DiskVolume, DiskFile, or DiskAlias interface, depending on what type of object the java.io.File represents. Also, the FileRegistry.createAppFile creates an AppFile from a java.io.File object. The AppFile interface implements the DiskFile interface.

Get information on drives, directories, and files

Once you have an object implementing DiskObject, you can obtain information such as its creation and modification dates, its icons, version information, FinderInfo, etc.

Get settings for files

The following table shows the values returned from the DiskFile.getFlags() method, and those which can be set using the DiskFile.setFlags() method.

In each case, the flag is a public static member of the DiskFile interface, and its value is an in with just one bit on.

DiskFile flags
JConfig value | Win | Mac | Nix
--- | --- | --- | ---
FILE_EXECUTABLE | G | G | .
FILE_DIR | . | . | .
FILE_HIDDEN | . | . | .
FILE_STATIONERY | . | . | .
FILE_NAME_LOCKED | . | . | .
FILE_CUSTOM_ICON | . | . | .
FILE_HAS_BNDL | . | . | .
FILE_BEEN_INITED | . | . | .
FILE_NO_INITS | . | . | .
FILE_SHARED | . | . | .
FILE_READONLY | . | . | .
FILE_SYSTEM | . | . | .
FILE_ARCHIVE | . | . | .
FILE_DEVICE | . | . | .
FILE_TEMP | . | . | .
FILE_SPARSE | . | . | .
FILE_REPARSEPOINT | . | . | .
FILE_COMPRESSED | . | . | .
FILE_OFFLINE | . | . | .
FILE_NOT_CONTENT_INDEXED | . | . | .
FILE_ENCRYPTED | . | . | .

Working with aliases

Given an object implementing the DiskObject interface, you can use java's 'instanceof' keyword to determine whether it's an alias or not. If it implements the DiskAlias interface, it's an alias.

Given an object implementing the DiskAlias interface, you can resolve the alias using the FileRegistry.resolveAlias() method. You can choose whether to allow or disallow user interaction.

The FileRegistry.createAlias() method lets you create an alias. You pass into this method a java.io.File object which represents the file you want to make into an alias, and an object implementing the DiskObject interface which you want the alias to point to. The new alias file must exist.

Working with file systems

The latest version of JConfig includes a FileSystem interface, which represents the file system underlying a particular hierarchy of volumes and directories. The FileRegistry.getFileSystems() method returns a list of the mounted file systems as an array of FileSystem objects. You can query each FileSystem object for such information as its free and available space, its mount point, etc. Also, the DiskObject.getFileSystem() method returns a FileSystem object representing the FileSystem on which the DiskObject is mounted. These methods are currently implemented only in the Linux version, but will be implemented for other platforms in the near future.

## Working with Web Browsers

JConfig lets you launch files or URLs in the user's Web browser.

Launching a URL or file

Use the FileRegistry.launchURL() method to launch a URL or file. The 'url' argument must be a fully-qualified URL in quoted-printable form, e.g.:

      http://www.tolstoy.com
      file:///Blossom/A%20Very%20Special%20Blossom.jpg

On Mac, if the user does not have Internet Config installed, applications with the creator types 'MSIE' and 'MOS!' are searched for. This also occurs if Internet Config is installed, but returns an error.

The creator types which are searched for in this case are stored in JConfig.shlb, in a resource of type 'brws', with ID 5000. To change the browser creators which are searched for, edit this resource to include the desired creator values.

On Windows, JConfig first tries to use DDE to launch the URL in a currently running browser. If that fails, a new browser is opened using either url.dll via ShellExecute, or WinExec.

## Working with Video Monitors

JConfig allows you to retrieve a list of the user's monitors, as well as information on each monitor.

Enumerating the user's monitors

Use the FileRegistry.getMonitors() method to obtain an array of the user's monitors. Only currently active screen devices are returned.

Use the FileRegistry.getMainMonitor() method to get an object representing the user's main monitor. On a Mac, the main monitor is the one with the menu bar.

If running on a VM other than those currently supported, a default monitor object with limited capabilities is returned from the preceding methods.

Getting monitor information

After retrieving a monitor object, as described in the preceding section, you can get information on it, such as the current bit depth, the bounds of the monitor, etc.

A common use is to find the 'workarea' of a monitor. This is the rectangular section which does not contain menu bars or tool bars. Use the Monitor.getWorkarea() method to get this information.

For instance, if the main monitor of a Mac is 640x480, and the menu bar is 20 pixels high, the workarea will be a rectangle where x=0, y=20, width=640, and height=460.

Note that the Rectangles returned by the Monitor class are in global coordinates. On a Mac, <0,0> is the upper left corner of the screen containing the menu bar. On Windows, <0,0> is the upper left corner of the screen.

## Working with External Processes

Two main interfaces let you work with external applications and processes: AppFile and AppProcess. AppFile implements the DiskFile interface, and represents an application as stored on disk. AppProcess represents a running instance of an AppFile.

Finding Applications

The FileRegistry singleton contains three methods named 'getApps', which allow you to find AppFile objects based on the name of an application ( e.g., SimpleText ) or the files which it can be used to open.

Converting a java.io.File into a JConfig AppFile object

The FileRegistry.createAppFile() method converts a java.io.File object into a JConfig AppFile object. The object must exist, and be an application. On Mac, this means the file type must be either 'APPL' or 'APPE'. On Windows, the file must end with ".exe".

Creating processes

You create an AppProcess from an AppFile using the AppFile's performCommand() method. For instance, if you want to launch an application with a document, you call the AppFile's getCommand() method with the constant 'kAppCommandOpenDoc', which returns an AppCommand object. Then, you use the AppCommand's addArg() method to add arguments to the command, in this case, the file to open. Then, you pass the AppCommand object to the performCommand() method. Assuming that no error occured, the performCommand() method returns an AppProcess object representing the running process.

Sending messages to processes

Objects which implement the AppProcess interface have a performCommand() method, which is similar to the method of the same name of the AppFile interface, which was described in the previous section. This lets you send commands to a running process, such as a set of files to open or print. The process must have been created using the performCommand() method of an AppFile object.

Getting Information on processes

The AppProcess.getPlatformData() method returns platform-specific data on a process. On Mac, this is the process' ProcessSerialNumber, and on Windows it's the process' HWND and other information. You can use these to send specialized messages to processes.

## Working with File Types

JConfig contains two platform-specific classes for working with file types: FinderInfo represents a Mac creator/file type pair ( e.g., <'ttxt','TEXT'> ), and FileExtension represents a Windows file extension ( e.g., ".txt" ). In addition, the convenience class FileType represents a cross-platform file type; you initialize a FileType object using either a FinderInfo or FileExtension object, and can use the FileType object to convert between Mac creator/file type codes and Windows file extensions. FileType uses the FileRegistry to do the conversion.

Converting between Mac and Windows

The FileRegistry findExtensions() and findFinderInfo() methods let you convert between Windows file extensions and Mac creator/file type codes.

Getting the file type of a file

The FileRegistry.getFileType() method takes a java.io.File object, and returns a FileType object which contains a cross-platform representation of the file type of that file. The method of FileType let you obtain the Windows file name extension or Mac file type code associated with that file type.

Getting the file types associated with an application

The AppFile.getFileTypes() method returns an array of the file types associated with an application.

## Customizing JConfig

jconfig.cfg

The file 'jconfig.cfg' supplied with this distribution is a default version of the Internet Config file mapping database. This database is used to map between file extensions, Mac creator/file types, and MIME types.

On Mac, if Internet Config is installed, JConfig uses Internet Config to do the mapping between file types, which will use the settings which have been configured by the user.

However, on Mac if Internet Config is not installed, or on platforms other than Mac, the file 'jconfig.cfg' will be used to do the mappings.

If you want to provide your own version of this file, you can use the application 'IC Res Copy' which is provided in the Mac section of this distribution, inside the 'macrescp' folder. This folder contains a file which describes the use of the 'IC Res Copy' application. See the 'macinfo.html' file for general information on the Mac section of this distribution. You will, of course, need to have access to a Mac to use this application.

If you don't have access to a Mac, you'll need to write a small program which creates your own version of 'jconfig.cfg'. The format of the IC file mapping database is straightforward, and is provided with the IC Programming Kit.

In any case, if you want to supply your own version, it must be named 'jconfig.cfg'.

jcfactrz.txt

The file 'jcfactrz.txt' tells JConfig which platform-dependent modules to attempt to load. See the documentation of the FileRegistryFactoryI interface for more information on this file.

## Unimplemented Features

These features are not currently implemented, but will be in the near future.

- The search flags for the FileRegistry.getApps() methods are only used if the 'maxToReturn' argument is 1, and all three search levels map to the same search level.
- The 'flags' and 'preferredBrowsers' arguments to FileRegistry.launchURL() are not yet implemented.
- The Monitor.setDepth() and Monitor.setResolution() methods are not yet implemented.
- On Windows, the FileRegistry.getProcesses() method is not yet implemented.
- On Unix, only the file browsing related features have been implemented so far.

Main Page · JConfig · ImageMeister · System Properties Repository · Native Macros · Free Samples · WordMeister · Java Freeware · Links · Contact Us

Copyright (c) 1997-2002 Samizdat Productions. All Rights Reserved.
JConfig and ImageMeister are trademarks of Samizdat Productions. Other trademarks are the property of their respective owners.
samizdat@tolstoy.com