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.
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.
To create a new image CODEC for Gloria, do the following things.
GloriaCodec
interface (see the next section)
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.
GloriaCodec
interfaceAny 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.
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.
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