## com.bbn.openmap.image
Class ImageServer

    java.lang.Object
      com.bbn.openmap.image.ImageServer

All Implemented Interfaces:
  PropertyConsumer

Direct Known Subclasses:
  MapRequestHandler, WmsRequestHandler

public class ImageServer
extends java.lang.Object
implements PropertyConsumer

The image server is the class you want to deal with when creating images from the ImageGenerator. It takes a properties file and sets up the image generator based on those properties. It also has this queuing thing going so that requests can stack up while the image generator is working on requests, and it will notify the requestor when the image is ready.

The ImageServer generally has the layers on the map predefined at construction, although you can change the layers that it has. When setting the layer array, do not use the same layer in two different slots of the array - it may not give you the expected map, and may mess around with the timing issues that the ImageGenerator takes care of. If you want to reorder the layers, do so before adding your request to the ImageServer. Additionally, each request has the option of not using certain layers in the ImageServer layer array, by turning off the appropriate bits in the layer mask. Understand that the image for a request will be created based on the layer array contents and the request layer mask at the time the request processing is started, not when it is submitted.

Right now, the ImageServer is single threaded - processing requests one after another. The request setup was written to support multi-threaded processing, though, where each image could be generated in it's own thread. That code is not written - maybe someday.

``

                        # If the ImageServer is created and given a prefix (in this example,
                        # 'imageServer') the properties file should contain the properties:
                        imageServer.layers=<layer1 layer2 ...>
                        layer1.className=<classname>
                        layer1.prettyName=<pretty name of layer>
                        # Add other attributes as required by layer1...
                        layer2.className=<classname>
                        layer2.prettyName=<pretty name of layer>
                        # Add other attributes as required by layer2...
                        # First formatter listed is default.
                        imageServer.formatters=<formatter1 formatter2 ...>
                        formatter1.class=<classname of formatter 1>
                        # Add other formatter1 properties
                        formatter2.class=<classname of formatter 2>

NOTE: If you simply hand the ImageServer a standard openmap.properties file, it works with the addition of the first two attributes except WITHOUT the 'imageServer.' prefix. New for 4.5: If the layers property is not defined, then the openmap.layers property is used to define which layers are available for the ImageServer.

Field Summary
`static java.lang.String` `AntiAliasingProperty` Property to turn on anti-aliasing.
`protected java.awt.Paint` `background` Paint object used for map backgrounds.
`static java.lang.String` `BackgroundProperty` Property to set the background color.
`protected boolean` `doAntiAliasing` Flag to do graphics and text anti-aliasing on the map image.
`protected ImageFormatter` `formatter` The Image formatter for the output image.
`protected java.util.Hashtable` `imageFormatters` Hashtable of ImageFormatters available to be used.
`static java.lang.String` `ImageFormattersProperty` Property for the image formatter list of available formats.
`static java.lang.String` `ImageServerLayersProperty` Property for space separated layers.
`protected Layer[]` `layers` The array of layers on the map.
`static java.lang.String` `OpenMapPrefix` OpenMap prefix
`protected java.lang.String` `propertiesPrefix` A place to hold on to a property prefix in case one is used.

Fields inherited from interface com.bbn.openmap.PropertyConsumer
`EditorProperty, initPropertiesProperty, LabelEditorProperty, ScopedEditorProperty`

Constructor Summary
`protected` `ImageServer()` Empty constructor that expects to be configured later.
`` `ImageServer(Layer[] layers, ImageFormatter formatter)` Create an ImageServer from an array of Layers and an ImageFormatter.
`` `ImageServer(java.util.Properties props)` To create the image server, you hand it a set of properties that let it create an array of layers, and also to set the properties for those layers.
`` `ImageServer(java.lang.String prefix, java.util.Properties props)` Same as the other constructor, except that the properties can have a prefix in front of them.
`` `ImageServer(java.lang.String prefix, java.util.Properties props, java.util.Hashtable instantiatedLayers)` Create an ImageServer that should be configured with a Properties file.

Method Summary
`int` `calculateVisibleLayerMask()` This method returns a integer representing a mask created from the visibility settings of the layers.
`protected java.awt.Graphics` `createGraphics(ImageFormatter formatter, int width, int height)` Create a java.awt.Graphics to use for an image.
`byte[]` `createImage(Projection proj)` Use the ProjectionPainter interface of the layers to create an image.
`byte[]` `createImage(Projection proj, int scaledWidth, int scaledHeight)` Use the ProjectionPainter interface of the layers to create an image.
`byte[]` `createImage(Projection proj, int scaledWidth, int scaledHeight, int includedLayerMask)` Use the ProjectionPainter interface of the layers to create an image.
`byte[]` `createImage(Projection proj, int scaledWidth, int scaledHeight, int includedLayerMask, java.awt.Paint background)` Use the ProjectionPainter interface of the layers to create an image.
`byte[]` `createImage(Projection proj, int scaledWidth, int scaledHeight, java.util.List showLayers)` Use the ProjectionPainter interface of the layers to create an image.
`byte[]` `createImage(Projection proj, int scaledWidth, int scaledHeight, java.util.List showLayers, java.awt.Paint background)` Use the ProjectionPainter interface of the layers to create an image.
`static java.lang.String` `createImageFile(java.lang.String prefix, java.util.Properties props, Projection proj, java.lang.String outputPath)` For convenience, to create an image file based on the contents of a properties file (like an openmap.properties file).
`java.awt.Paint` `getBackground()` Get the Paint to use for image backgrounds.
`java.awt.Paint` `getBackground(java.util.Properties props, java.lang.String propertyKey)` Determine the background color based on property settings.
`boolean` `getDoAntiAliasing()` Find out whether anti-aliasing is used when creating the image.
`protected byte[]` `getFormattedImage(ImageFormatter formatter, int scaledWidth, int scaledHeight)` Format the image that is contained in the ImageFormatter, scaling to a particular size if the scaledWidth and scaledHeight are greater than 0.
`ImageFormatter` `getFormatter()` Get the ImageFormatter currently used for the image creation.
`java.util.Hashtable` `getFormatters()` Get the Hashtable used to hold the ImageFormatters.
`protected ImageFormatter` `getFormatters(java.util.Properties p)` Create an ImageFormatter from the contents of a properties object.
`Layer[]` `getLayers()` Retrieve the current set of layers used for requests.
`protected Layer[]` `getLayers(java.util.Properties p)` Create an array of Layers from a properties object.
`protected Layer[]` `getLayers(java.util.Properties p, java.util.Hashtable instantiatedLayers)` Create an array of Layers from a properties object.
`protected Layer[]` `getMaskedLayers(int layerMask)` Given a integer that represents, bitwise, the layers that you want out of the current list held by the ImageServer layer array, return an array of those layers.
`java.util.Properties` `getProperties(java.util.Properties props)` Part of the PropertyConsumer interface.
`java.util.Properties` `getPropertyInfo(java.util.Properties list)` Part of the PropertyConsumer interface.
`java.lang.String` `getPropertyPrefix()` Part of the PropertyConsumer interface.
`static void` `main(java.lang.String[] argv)` The ImageServer class main function will create a map image from a modified openmap.properties file.
`void` `setBackground(java.awt.Paint bg)` Set the Paint to use for image backgrounds.
`void` `setDoAntiAliasing(boolean set)` Set whether anti-aliasing is used when creating the image.
`void` `setFormatter(ImageFormatter f)` Set the ImageFormatter to be used for ImageCreation.
`boolean` `setFormatter(java.lang.String formatterLabel)` Set the default formatter to the one with the given label.
`void` `setFormatters(java.util.Hashtable iFormatters, java.lang.String defaultFormatterKey)` Set the ImageFormatter Hashtable to set up the possible choices for image formats.
`void` `setLayers(Layer[] newLayers)` Set the layers used on the NEXT request that is processed.
`void` `setProperties(java.util.Properties props)` Set the layers and image type in the properties.
`void` `setProperties(java.lang.String prefix, java.util.Properties props)` Set the layers and image type in the properties.
`void` `setProperties(java.lang.String prefix, java.util.Properties props, java.util.Hashtable instantiatedLayers)` Set the layers and image type in the properties.
`void` `setPropertyPrefix(java.lang.String prefix)` Part of the PropertyConsumer interface.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### formatter

    protected ImageFormatter formatter

  The Image formatter for the output image.

### imageFormatters

    protected java.util.Hashtable imageFormatters

  Hashtable of ImageFormatters available to be used.

### layers

    protected Layer[] layers

  The array of layers on the map. First is on top.

### ImageServerLayersProperty

    public static final java.lang.String ImageServerLayersProperty

  Property for space separated layers.

  See Also:
    Constant Field Values

### OpenMapPrefix

    public static final java.lang.String OpenMapPrefix

  OpenMap prefix

  See Also:
    Constant Field Values

### ImageFormattersProperty

    public static final java.lang.String ImageFormattersProperty

  Property for the image formatter list of available formats. This propery should contain a space separated list of marker names.

  See Also:
    Constant Field Values

### AntiAliasingProperty

    public static final java.lang.String AntiAliasingProperty

  Property to turn on anti-aliasing.

  See Also:
    Constant Field Values

### BackgroundProperty

    public static final java.lang.String BackgroundProperty

  Property to set the background color.

  See Also:
    Constant Field Values

### doAntiAliasing

    protected boolean doAntiAliasing

  Flag to do graphics and text anti-aliasing on the map image.

### propertiesPrefix

    protected java.lang.String propertiesPrefix

  A place to hold on to a property prefix in case one is used. Useful for ImageServer properties files where more than one image server is defined.

### background

    protected java.awt.Paint background

  Paint object used for map backgrounds.

Constructor Detail

### ImageServer

    protected ImageServer()

  Empty constructor that expects to be configured later.

### ImageServer

    public ImageServer(java.util.Properties props)

  To create the image server, you hand it a set of properties that let it create an array of layers, and also to set the properties for those layers. The properties file for the ImageServer looks strikingly similar to the openmap.properties file. So, all the layers get set up here...

### ImageServer

    public ImageServer(java.lang.String prefix,
                       java.util.Properties props)

  Same as the other constructor, except that the properties can have a prefix in front of them. The format of the prefix has to match how the property is specified the the properties file, which may include the period - i.e server1.imageServer.layers, the server1. is the prefix that should get passed in. The ImageMaster does this.

### ImageServer

    public ImageServer(java.lang.String prefix,
                       java.util.Properties props,
                       java.util.Hashtable instantiatedLayers)

  Create an ImageServer that should be configured with a Properties file. The prefix given is to scope the ImageServer properties to this instance. The Hashtable is for reusing any layers that may already be instantiated.

### ImageServer

    public ImageServer(Layer[] layers,
                       ImageFormatter formatter)

  Create an ImageServer from an array of Layers and an ImageFormatter. It's assumed that the layers are already configured.

Parameters:
  `layers` - the array of layers.
  `formatter` - the ImageFormatter to use for the output image format.

Method Detail

### setDoAntiAliasing

    public void setDoAntiAliasing(boolean set)

  Set whether anti-aliasing is used when creating the image.

### getDoAntiAliasing

    public boolean getDoAntiAliasing()

  Find out whether anti-aliasing is used when creating the image.

### setLayers

    public void setLayers(Layer[] newLayers)

  Set the layers used on the NEXT request that is processed. Will not affect any image currently being created.

  Parameters:
    `newLayers` - an array of com.bbn.openmap.Layer objects, already configured and ready to respond to a projectionChanged method call.

### getLayers

    public Layer[] getLayers()

  Retrieve the current set of layers used for requests.

  Returns:
    Layer[]

### createImage

    public byte[] createImage(Projection proj)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things.

  Parameters:
    `proj` - projection of map.
  Returns:
    a byte[] representing the formatted image.

### createImage

    public byte[] createImage(Projection proj,
                              int scaledWidth,
                              int scaledHeight)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things.

  Parameters:
    `proj` - projection of map.
    `scaledWidth` - scaled pixel width of final image. If you don't want it scaled, use -1.
    `scaledHeight` - scaled pixel height of final image. If you don't want it scaled, use -1.
  Returns:
    a byte[] representing the formatted image.

### createImage

    public byte[] createImage(Projection proj,
                              int scaledWidth,
                              int scaledHeight,
                              java.util.List showLayers)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things. The background used for the image is the one set in this ImageServer object.

  Parameters:
    `proj` - projection of map.
    `scaledWidth` - scaled pixel width of final image. If you don't want it scaled, use -1.
    `scaledHeight` - scaled pixel height of final image. If you don't want it scaled, use -1.
    `showLayers` - Layer marker names reflecting the layers that should be part of this image.
  Returns:
    a byte[] representing the formatted image.

### createImage

    public byte[] createImage(Projection proj,
                              int scaledWidth,
                              int scaledHeight,
                              java.util.List showLayers,
                              java.awt.Paint background)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things. The background used for the image is the one set in this ImageServer object.

  Parameters:
    `proj` - projection of map.
    `scaledWidth` - scaled pixel width of final image. If you don't want it scaled, use -1.
    `scaledHeight` - scaled pixel height of final image. If you don't want it scaled, use -1.
    `showLayers` - Layer marker names reflecting the layers that should be part of this image.
    `background` - the Paint to be used for the background of this image.
  Returns:
    a byte[] representing the formatted image.

### calculateVisibleLayerMask

    public int calculateVisibleLayerMask()

  This method returns a integer representing a mask created from the visibility settings of the layers.

### createImage

    public byte[] createImage(Projection proj,
                              int scaledWidth,
                              int scaledHeight,
                              int includedLayerMask)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things. Uses the default background set in the ImageServer.

  Parameters:
    `proj` - projection of map.
    `scaledWidth` - scaled pixel width of final image. If you don't want it scaled, use -1.
    `scaledHeight` - scaled pixel height of final image. If you don't want it scaled, use -1.
    `includedLayerMask` - a mask signifying which of the ImageServer layers to use in the image. It's assumed that the called knows which layers are desired. Bit 1 of the mask refers to layer[0], etc. A bit turned on means the layer will be included.
  Returns:
    a byte[] representing the formatted image.

### createImage

    public byte[] createImage(Projection proj,
                              int scaledWidth,
                              int scaledHeight,
                              int includedLayerMask,
                              java.awt.Paint background)

  Use the ProjectionPainter interface of the layers to create an image. This approach avoids some of the timing issues that the thread model of the MapBean and Layers that seem to pop up from time to time. They are Swing components, you know. They were designed to be part of a GUI. So, this is a serialized, safe way to do things.

  Parameters:
    `proj` - projection of map.
    `scaledWidth` - scaled pixel width of final image. If you don't want it scaled, use -1.
    `scaledHeight` - scaled pixel height of final image. If you don't want it scaled, use -1.
    `includedLayerMask` - a mask signifying which of the ImageServer layers to use in the image. It's assumed that the called knows which layers are desired. Bit 1 of the mask refers to layer[0], etc. A bit turned on means the layer will be included.
    `background` - the background Paint to use for the image, behind the layers.
  Returns:
    a byte[] representing the formatted image.

### createGraphics

    protected java.awt.Graphics createGraphics(ImageFormatter formatter,
                                               int width,
                                               int height)

  Create a java.awt.Graphics to use for an image. The Graphics will affect the image contained within the ImageFormatter.

  Parameters:
    `formatter` - the ImageFormatter containing the image.
    `width` - the pixel width of the image.
    `height` - the pixel height of the image.

### getFormattedImage

    protected byte[] getFormattedImage(ImageFormatter formatter,
                                       int scaledWidth,
                                       int scaledHeight)

  Format the image that is contained in the ImageFormatter, scaling to a particular size if the scaledWidth and scaledHeight are greater than 0.

### setProperties

    public void setProperties(java.util.Properties props)

  Set the layers and image type in the properties.

  Specified by:
    `setProperties` in interface `PropertyConsumer`
  Parameters:
    `props` - a properties object that the PropertyConsumer can use to retrieve expected properties it can use for configuration.

### setProperties

    public void setProperties(java.lang.String prefix,
                              java.util.Properties props)

  Set the layers and image type in the properties. The properties might have a prefix in the file.

  Specified by:
    `setProperties` in interface `PropertyConsumer`
  Parameters:
    `prefix` - a String used by the PropertyConsumer to prepend to each property value it wants to look up - setList.getProperty(prefix.propertyKey). If the prefix had already been set, then the prefix passed in should replace that previous value.
    `props` - a Properties object that the PropertyConsumer can use to retrieve expected properties it can use for configuration.

### setProperties

    public void setProperties(java.lang.String prefix,
                              java.util.Properties props,
                              java.util.Hashtable instantiatedLayers)

  Set the layers and image type in the properties. The properties might have a prefix in the file.

### getBackground

    public java.awt.Paint getBackground(java.util.Properties props,
                                        java.lang.String propertyKey)

  Determine the background color based on property settings. If the property key isn't found, the openmap.BackgroundColor property will be used. If that isn't found, then Color.white will be returned as default.

  Parameters:
    `props` - properties to check
    `propertyKey` - first key to check for.
  Returns:

### getProperties

    public java.util.Properties getProperties(java.util.Properties props)

  Part of the PropertyConsumer interface. Doesn't do anything yet.

  Specified by:
    `getProperties` in interface `PropertyConsumer`
  Parameters:
    `props` - a Properties object to load the PropertyConsumer properties into. If getList equals null, then a new Properties object should be created.
  Returns:
    Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

### getPropertyInfo

    public java.util.Properties getPropertyInfo(java.util.Properties list)

  Part of the PropertyConsumer interface.

  Specified by:
    `getPropertyInfo` in interface `PropertyConsumer`
  Parameters:
    `list` - a Properties object to load the PropertyConsumer properties into. If getList equals null, then a new Properties object should be created.
  Returns:
    Properties object containing PropertyConsumer property values. If getList was not null, this should equal getList. Otherwise, it should be the Properties object created by the PropertyConsumer.

### setPropertyPrefix

    public void setPropertyPrefix(java.lang.String prefix)

  Part of the PropertyConsumer interface. Set the Properties prefix to use to scope the relevant properties passed into the setProperties method.

  Specified by:
    `setPropertyPrefix` in interface `PropertyConsumer`
  Parameters:
    `prefix` - the prefix String.

### getPropertyPrefix

    public java.lang.String getPropertyPrefix()

  Part of the PropertyConsumer interface. Get the Properties prefix used to scope the relevant properties passed into the setProperties method.

  Specified by:
    `getPropertyPrefix` in interface `PropertyConsumer`
  Returns:
    the prefix string

### getMaskedLayers

    protected Layer[] getMaskedLayers(int layerMask)

  Given a integer that represents, bitwise, the layers that you want out of the current list held by the ImageServer layer array, return an array of those layers.

  Parameters:
    `layerMask` - bit mask for desired layers, bit 0 is layer 0.
  Returns:
    layer[]

### getFormatter

    public ImageFormatter getFormatter()

  Get the ImageFormatter currently used for the image creation.

  Returns:
    ImageFormatter.

### setFormatter

    public void setFormatter(ImageFormatter f)

  Set the ImageFormatter to be used for ImageCreation.

### setFormatter

    public boolean setFormatter(java.lang.String formatterLabel)

  Set the default formatter to the one with the given label. The label can be retrieved from the ImageFormatter.

  Parameters:
    `formatterLabel` - String for a particular formatter.
  Returns:
    true if label matches up with a known formatter, false if no formatter found.

### getFormatters

    public java.util.Hashtable getFormatters()

  Get the Hashtable used to hold the ImageFormatters. The label for each one is the lookup for it in the Hashtable.

  Returns:
    Hashtable of ImageFormatters.

### setFormatters

    public void setFormatters(java.util.Hashtable iFormatters,
                              java.lang.String defaultFormatterKey)

  Set the ImageFormatter Hashtable to set up the possible choices for image formats.

  Parameters:
    `iFormatters` - Hashtable of ImageFormatters
    `defaultFormatterKey` - the key label of the formatter to use for a default.

### getFormatters

    protected ImageFormatter getFormatters(java.util.Properties p)

  Create an ImageFormatter from the contents of a properties object.

  Parameters:
    `p` - Properties used to initialize the Properties.
  Returns:
    default formatter.

### getLayers

    protected Layer[] getLayers(java.util.Properties p)

  Create an array of Layers from a properties object.

### getLayers

    protected Layer[] getLayers(java.util.Properties p,
                                java.util.Hashtable instantiatedLayers)

  Create an array of Layers from a properties object. Reuse the layer from the hashtable if it's there under the same property name. The Hashtable is kept for an ImageServer that is used buy an ImageMaster or another object that is using different layers for it's image. It will reuse the layers it's already created if the marker names are the same.

  Parameters:
    `p` - properties
    `instantiatedLayers` - a hashtable containing layers, with the prefix layer name used as the key.

### createImageFile

    public static java.lang.String createImageFile(java.lang.String prefix,
                                                   java.util.Properties props,
                                                   Projection proj,
                                                   java.lang.String outputPath)
                                            throws java.net.MalformedURLException,
                                                   java.io.IOException

  For convenience, to create an image file based on the contents of a properties file (like an openmap.properties file).

  Parameters:
    `prefix` - The prefix for the ImageServer properties (layers and formatters) to use in the properties file. If defined, then this method will look for 'prefix.layers' and prefix.formatters' properties. If null, then this method will look 'layers' and 'formatters' properties.
    `props` - The properties to use for defining the layers and plugins to use on the map image. Standard openmap.properties formats for layer definitions. See the standard openmap.properties file for more details on how to define layers and plugins.
    `proj` - The projection to use for the map. If null, then the Environment projection properties will be looked for in the Properties.
    `outputPath` - The output path for the image file. The image file should not have an appendix defined. This method will check which formatter is being used, and will assign one based on the image format (leave off the ., too).
  Returns:
    the final path of the written image file, with the chosen appendix attached.
  Throws:
    `java.net.MalformedURLException`
    `java.io.IOException`

### setBackground

    public void setBackground(java.awt.Paint bg)

  Set the Paint to use for image backgrounds.

### getBackground

    public java.awt.Paint getBackground()

  Get the Paint to use for image backgrounds.

### main

    public static void main(java.lang.String[] argv)

  The ImageServer class main function will create a map image from a modified openmap.properties file.

                         java com.bbn.openmap.image.ImageServer -properties (path
                          to properties file) -file (path to output image)

  The path to the output image should not have an appendix on it, that will get assigned depending on what image format is used.

Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details