Image CODEC for Gloria API Specification

This document contains the API specification of the image CODEC for Gloria. (CODEC is an abbreviated expression for encoder/decoder.)

Note: This is a tentative plan. The API may change in the future.

Introduction

Gloria (version 0.30 and later) comes with a plug-in mechanism that allows you to supply image CODECs or filters for yourself. By default, you find a few CODECs in the $GLORIA/codec directory and several filters in the $GLORIA/filter directory all of which are in the JAR format, where $GLORIA is the directory in which Gloria is installed. The plug-in mechanism is a powerful way to add new functions to Gloria.

What you have to do

To create a new image CODEC for Gloria, do the following things.

  1. Implement the GloriaCodec interface (see the next section)
  2. Archive class files in a JAR file
  3. Put the JAR file in $GLORIA/codec

The JAR file may contain more than one class file, but its name must coincide with the name of the class that implements the GloriaCodec interface, except for the extension of the file. For example, if ExampleCodec.class is the class file that implements the GloriaCodec interface, the JAR file should be ExampleCodec.jar.

Restart Gloria to load newly added plug-ins.

The GloriaCodec interface

Any image CODECs for Gloria must implement the GloriaCodec interface. A class that implements the GloriaCodec interface wraps the detail of encoding or decoding. The GloriaCodec interface is shown  in the following.

/** GloriaCodec
 *  Copyright (C) 1999 Satoru Muto
 *  All rights reserved.
 */
package gloria;
import java.awt.image.BufferedImage;
import java.util.Map;
public interface GloriaCodec {
public abstract BufferedImage getImage(String filename) throws Exception;
public abstract void putImage(BufferedImage image, String filename) throws Exception;
public abstract boolean supportsLoad();
public abstract boolean supportsSave();
public abstract String[] getExtensions();
public abstract Map getOption();
public abstract void setOption(Map map);
public abstract String getName();
public abstract String getDescription();
public abstract String getVersion();
public abstract String getAuthor();
public abstract String getComment(); }

The getImage(String filename) method is used to load an image from a file. It should return an instance of BufferedImage and throw an instance of Exception if some error occured while processing. The putImage(BufferedImage image, String filename) is used to save an image to a file. It should also throw an instance of Exception if some error occured while processing.

The supportsLoad() method should return true if the plug-in supports loading or false if not. Similarly, the supportsSave() method should return true if the plug-in supports saving or false if  not.

The getExtensions() method should return an array of String, each element representing a file extension relevant to the plug-in. For example, including "jpg" and "jpeg" in the array implies that a file with a name *.jpg or *.jpeg can be handled by the plug-in.

The getOption() method may be used to get an instance of Map that can be used as a backing store of options. Conversely, the setOption(Map map) method may be used to set options. [These two methods are only placeholders at present. You may implement getOption() to return null or setOption(Map map) to be NOP.] 

The getName() method should return the name of the plug-in. The string returned by getName() should represent the essential role of the plug-in and be as short as possible. The getDescription() method should give a more detailed description about the plug-in. The getVersion() method should return the version. The getAuthor() method should return the name of the author. The getComment() method can be used to indicate copyright notice, e-mail address of the author, and so on. Those methods are used to display information about the plug-in in Gloria.

An implementation of the GloriaCodec interface - JpegImageCodec

Gloria comes with a default implementation of JPEG CODEC, which is packed in JpegImageCodec.jar as a Gloria plug-in. JpegImageCodec is a class that implements the GloriaCodec interface, which is shown in the following.

/** JpegImageCodec
 *  Copyright (C) 1999 Satoru Muto
 *  All rights reserved.
 */
package gloria.codec;

import com.sun.image.codec.jpeg.*;
import java.awt.image.*;
import java.io.*;
import java.util.*;

public class JpegImageCodec implements gloria.GloriaCodec {

    public BufferedImage getImage(String filename) throws Exception {
        BufferedImage image = null;

        FileInputStream fis = new FileInputStream(filename);
        JPEGImageDecoder decoder = JPEGCodec.createJPEGDecoder(fis);
        image = decoder.decodeAsBufferedImage();
        fis.close();

        return image;
    }

    public void putImage(BufferedImage image, String filename) throws Exception {
        FileOutputStream fos = new FileOutputStream(filename);
        JPEGImageEncoder encoder = JPEGCodec.createJPEGEncoder(fos);
        encoder.encode(image);
        fos.close();
    }

    public boolean supportsLoad() {
        return true;
    }

    public boolean supportsSave() {
        return true;
    }

    public String[] getExtensions() {
        return new String[] {"jpg", "jpeg"};
    }

    public Map getOption() {
        return null;
    }

    public void setOption(Map map) {
        // Do nothing!
    }

    public String getName() {
        return "JPEG";
    }

    public String getDescription() {
        return "JPEG image CODEC for Gloria.";
    }

    public String getVersion() {
        return "1.0";
    }

    public String getAuthor() {
        return "Satoru Muto";
    }

    public String getComment() {
        return "Copyright (C) 1999 Satoru Muto";
    }
}

This example code is sufficient to see how to implement the GloriaCodec interface. Note that the real task of encoding or decoding is done by a JPEGImageEncoder or a JPEGImageDecoder in the com.sun.image.codec.jpeg package, which is not part of the Java Platform. It is assumed that you prepare classes that really do the job. Remember that the GloriaCodec interface is used only as a wrapper for Gloria.

Additional note

Gloria knows the format of an image file from its extension. Multiple CODECs for a single extension will cause a problem, so make sure that only one CODEC is related to an extension by removing plug-ins in the $GLORIA/codec directory if necessary.


Copyright (C) 1999 Satoru Muto