001: /* Copyright (c) 2001 - 2007 TOPP - www.openplans.org. All rights reserved.
002: * This code is licensed under the GPL 2.0 license, availible at the root
003: * application directory.
004: */
005: package org.vfny.geoserver.wms;
006:
007: import org.geotools.factory.Factory;
008: import java.util.Set;
009:
010: /**
011: * Constructs a live GetLegendGraphicProducer.
012: *
013: * <p>
014: * An instance of this interface should exist for all legend producers which
015: * want to take advantage of the dynamic plugin system. In addition to
016: * implementing this interface GetLegendGraphic producers should have a
017: * services file:
018: * </p>
019: *
020: * <p>
021: * <code>org.vfny.geoserver.responses.wms.GetLegendGraphicProducerSpi</code>
022: * </p>
023: *
024: * <p>
025: * The file should contain a single line which gives the full name of the
026: * implementing class.
027: * </p>
028: *
029: * <p>
030: * example:<br/><code>e.g.
031: * org.vfny.geoserver.responses.wms.GIFLegendGraphicProducerSpi</code>
032: * </p>
033: *
034: * <p>
035: * The factories are never called directly by client code, instead the
036: * GeoTools' FactoryFinder class is used.
037: * </p>
038: *
039: * <p>
040: * The following example shows how a user might obtain GetLegendGraphicProducer
041: * capable of generating a legend graphic image in GIF format and send the
042: * generated legend to a file:
043: * </p>
044: *
045: * <p>
046: * <pre><code>
047: * GetLegendGraphicProducerSpi glf = null;
048: * Iterator it = FactoryFinder.factories(GetLegendGraphicProducerSpi.class);
049: * while (it.hasNext()) {
050: * GetLegendGraphicProducerSpi tmpGlf = (GetLegendGraphicProducerSpi) it.next();
051: * if (tmpGlf.canProduce("image/gif")) {
052: * glf = tmpGlf;
053: * break;
054: * }
055: * }
056: * GetLegendGraphicProducer producer = glf.createLegendProducer("image/gif");
057: * GetLegendGraphicRequest request = ...
058: * producer.produceLegendGraphic(request);
059: * OutputStream out = new FileOutputStream("/legend.gif");
060: * producer.writeTo(out);
061: * </code></pre>
062: * </p>
063: *
064: * @author Gabriel Roldan, Axios Engineering
065: * @version $Revision: 1.1 $
066: */
067: public interface GetLegendGraphicProducerSpi extends Factory {
068: /**
069: * Returns a descriptive name for the factory instance.
070: *
071: * @return a descriptive name for the factory instance
072: */
073: String getName();
074:
075: /**
076: * Returns a <code>java.util.Set<String></code> of the MIME types the
077: * legend producers this factory can create are able to handle.
078: *
079: * @return the Set of supported output image mime types.
080: */
081: Set getSupportedFormats();
082:
083: /**
084: * Checks if the GetLegendGraphicProducer instances this factory serves
085: * will be able of working properly (e.g., external dependencies are in
086: * place). This method should be used to avoid asking for producer
087: * instances if they are likely to fail.
088: *
089: * @return wether this factory is able to produce producer instances.
090: */
091: boolean isAvailable();
092:
093: /**
094: * Returns wether the legend producers created by this factory can create
095: * legend graphics in the specified output format.
096: *
097: * @param mimeType a MIME type string to check if this producer is able to
098: * handle.
099: *
100: * @return <code>true</code> if <code>mimeType</code> is an image format
101: * supported by the producers this factory serves.
102: */
103: boolean canProduce(String mimeType);
104:
105: /**
106: * Creates and instance of a GetLegendGraphicProducer suitable to create
107: * legend graphics in the specified image format.
108: *
109: * @param format the MIME type of the desired image
110: *
111: * @return a GetLegendGraphicProducer capable of creating legends in
112: * <code>format</code> image format.
113: *
114: * @throws IllegalArgumentException if <code>format</code> is not one of
115: * the MIME types this producer can create images in.
116: */
117: GetLegendGraphicProducer createLegendProducer(String format)
118: throws IllegalArgumentException;
119: }
|