dd.sim
Class Layer

java.lang.Object
  dd.sim.SimObject
      dd.sim.Layer

All Implemented Interfaces:

java.io.Serializable

public class Layer

extends SimObject

A collection of related pieces of information. This simulation map is (conceptually) split into multiple layers. Each layer has attributes related to some aspect of the simulation, such as population, traffic, or land use. Layers span over multiple cells, so the layer is used to query a map to retrieve relevant cells or obtain characteristics of cells.

Because of the tight connection between Maps and Layers, it is often unnecessary to create Layer objects directly. Instead, a layer can be created and associated with a map by calling the Map.createLayer() method. This has the advantage of ensuring that every map cell shares the same layer, rather than creating a different layer object for each cell, which could potentially cause model inconsistencies.

Author:

Eric Scharff

See Also:

Serialized Form

Field Summary

Fields inherited from class dd.sim.SimObject

attributes

Constructor Summary

Layer()
Creates a new unnamed layer.

Layer(java.lang.String layerName)
Creates a new named layer.

Method Summary

java.util.Collection	cellsWithValuesInRange(java.lang.String attributeName, float minValue, float maxValue) Finds all cells with attributes between a minimum and maximum value.
MapCell	cellWithMaxValue(java.lang.String attributeName) Finds a cell with the maximum value for some attribute.
MapCell	cellWithMaxValue(java.lang.String attributeName, java.util.Collection cells) Searches a subset of cells for a cell with the maximum value for some attribute.
MapCell	cellWithMinValue(java.lang.String attributeName) Finds a cell with the minimum value for some attribute.
MapCell	cellWithMinValue(java.lang.String attributeName, java.util.Collection cells) Searches a subset of cells for a cell with the minimum value for some attribute.
MapCell	cellWithValue(java.lang.String attributeName, int value) Finds the first cell with attribute equal to the specified value.
float	getAttribute(java.lang.String attributeName, MapCell cell) Queries this layer for an attribute associated with a specified cell.
java.lang.String	getName() Returns the name of this layer.
java.lang.Object	getObjectAttribute(java.lang.String attributeName, MapCell cell) Queries this layer for an attribute associated with a specified cell.
protected void	setCells(MapCell[][] mapCells) Associates this layer with cells from a map.

Methods inherited from class dd.sim.SimObject

addPropertyChangeListener, addPropertyChangeListener, debug, duplicate, error, fatal, filter, filter, firePropertyChange, getAttribute, getAttribute, getAttributes, getGlobalAttribute, getObjectAttribute, getObjectAttribute, incrementAttribute, incrementAttribute, isSet, log, out, readFromXML, readFromXML, removeAttribute, removePropertyChangeListener, setAttribute, setAttribute, setAttribute, setAttributes, setGlobalAttribute, warning, writeText, writeXML, writeXML

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Layer

public Layer()

Creates a new unnamed layer. This constructor should almost never be used because layers should have unique names.

Layer

public Layer(java.lang.String layerName)

Creates a new named layer. It is rare that layer is created directly using this constructor, because most layers are created dynamically from the map on which the layer exists. It is therefore desirable to create or query layers using the Map object.

Note that if a layer is created directly, it must be added to the map and linked to the map's cells.

Parameters:

layerName - name of this layer

See Also:

Map.createLayer(String)

Method Detail

getName

public java.lang.String getName()

Returns the name of this layer. Layer names are short human readable names. To distinguish layers from attributes, it is advisable to begin a layer name with a capital (not a lower-case) letter.

Returns:

the name of this layer

setCells

protected void setCells(MapCell[][] mapCells)

Associates this layer with cells from a map. This method is typically only invoked by the map that created the layer to bind the map and the layer.

Parameters:

mapCells - cells to which the layer was added

getAttribute

public float getAttribute(java.lang.String attributeName,
                          MapCell cell)

Queries this layer for an attribute associated with a specified cell. If the location has an attribute stored in this layer, that attribute is returned. Note that this is different than a non-cell-specific attribute. This is a convenience method for the more general-purpose getObjectAttribute method, which shares the same variables.

This call is equivalent to calling cell.getAttribute(attributeName, layer).

Parameters:

attributeName - name of the attribute to be queried

cell - cell with which the attribute is associated

Returns:

the value of that attribute in this layer on the cell specified

Throws:

java.util.NoSuchElementException - if there is no attribute with that name associated with that cell.

getObjectAttribute

public java.lang.Object getObjectAttribute(java.lang.String attributeName,
                                           MapCell cell)

Queries this layer for an attribute associated with a specified cell. If the location has an attribute stored in this layer, that attribute is returned. Note that this is different than a non-cell-specific attribute.

Parameters:

attributeName - name of the attribute to be queried

cell - cell with which the attribute is associated

Returns:

the value of that attribute in the cell on this layer specified, null if the attribute does not exist

cellWithMinValue

public MapCell cellWithMinValue(java.lang.String attributeName)

Finds a cell with the minimum value for some attribute. This method looks at all cells on the map and queries the attribute on this layer. The cell returned is the one with the minimum value for the specified attribute.

Parameters:

attributeName - attribute to query

Returns:

the cell whose value for the attribute on this layer has the smallest value

cellWithMaxValue

public MapCell cellWithMaxValue(java.lang.String attributeName)

Finds a cell with the maximum value for some attribute. This method looks at all cells on the map and queries the attribute on this layer. The cell returned is the one with the maximum value for the specified attribute.

Parameters:

attributeName - attribute to query

Returns:

the cell whose value for the attribute on this layer has the largest value

cellWithMinValue

public MapCell cellWithMinValue(java.lang.String attributeName,
                                java.util.Collection cells)

Searches a subset of cells for a cell with the minimum value for some attribute. This method searches all cells in the collection provided and queries each for the attribute on this layer. The cell returned is the one with the minimum value for the specified attribute.

Parameters:

attributeName - attribute to query

cells - cells (subset of the map) to search

Returns:

the cell whose value for the attribute on this layer has the smallest value

cellWithMaxValue

public MapCell cellWithMaxValue(java.lang.String attributeName,
                                java.util.Collection cells)

Searches a subset of cells for a cell with the maximum value for some attribute. This method searches all cells in the collection provided and queries each for the attribute on this layer. The cell returned is the one with the maximum value for the specified attribute.

Parameters:

attributeName - attribute to query

cells - cells (subset of the map) to search

Returns:

the cell whose value for the attribute on this layer has the largest value

cellsWithValuesInRange

public java.util.Collection cellsWithValuesInRange(java.lang.String attributeName,
                                                   float minValue,
                                                   float maxValue)

Finds all cells with attributes between a minimum and maximum value. This method queries every cell on the map for the current attribute, and returns all cells with attribute value between minValue and maxValue, inclusive.

Parameters:

attributeName - attribute to query

minValue - lower end of range

maxValue - upper end of range

Returns:

all cells where the attribute value >= minValue and <= maxValue

cellWithValue

public MapCell cellWithValue(java.lang.String attributeName,
                             int value)

Finds the first cell with attribute equal to the specified value. This method queries every cell on the map for the specified attribute, and returns the first cell it finds with attribute value equal to the specified value. This function is intended for use with attributes where each value is unique, like "base" (which indicates the turnNumber of the Player that owns the base). Since the query order is unspecified, if multiple cells have the same attribute value, it is possible that the a cell will be consistently ignored. In this case, use the cellsWithValuesInRange method instead.

Parameters:

attributeName - attribute to query

value - value to search for

Returns:

the first cell where the attribute value equals value, or null if no such cell is found.