ucar.nc2

Class Dimension

java.lang.Object

ucar.nc2.CDMNode

ucar.nc2.Dimension

All Implemented Interfaces:

java.lang.Comparable<Dimension>

public class Dimension
extends CDMNode
implements java.lang.Comparable<Dimension>

A Dimension is used to define the array shape of a Variable. A Variable can be thought of as a sampled function with Domain its Dimensions. A Dimension may be shared among Variables, which provides a simple yet powerful way of associating Variables. When a Dimension is shared, it has a unique name within its Group. It may have a coordinate Variable, which gives each index a coordinate value. A private Dimension cannot have a coordinate Variable, so use shared dimensions with coordinates when possible. The Dimension length must be > 0, except for an unlimited dimension which may have length = 0, and a vlen Dimension which has a length known only when the variable is read.

Immutable if setImmutable() was called, except for an Unlimited Dimension, whose size can change.

Note: this class has a natural ordering that is inconsistent with equals. TODO Dimension will be immutable in 6. TODO Dimension will not extend CDMNode in 6. TODO Dimension will not have a reference to its owning Group in 6. TODO Dimension.getFullName() will not exist in 6.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Dimension.Builder A builder of Dimensions.

Field Summary

Fields

Modifier and Type	Field and Description
static Dimension	VLEN A variable-length dimension: the length is not known until the data is read.

Fields inherited from class ucar.nc2.CDMNode

annotations, dodsname, group, immutable, parentstruct, shortName, sort

Constructor Summary

Constructors

Constructor and Description
Dimension(java.lang.String name, Dimension from) Deprecated. Use Dimension.builder()
Dimension(java.lang.String name, int length) Constructor
Dimension(java.lang.String name, int length, boolean isShared) Deprecated. Use Dimension.builder()
Dimension(java.lang.String name, int length, boolean isShared, boolean isUnlimited, boolean isVariableLength) Constructor

Method Summary

Modifier and Type	Method and Description
static Dimension.Builder	builder()
static Dimension.Builder	builder(java.lang.String name, int length) A builder with the Dimension name and length set
int	compareTo(Dimension odim) Dimensions with the same name are equal.
boolean	equals(java.lang.Object oo)
Group	getGroup() Deprecated. Do not use.
int	getLength() Get the length of the Dimension.
java.lang.String	getName() Get the name of the Dimension.
java.lang.String	getShortName() Get the name of the Dimension.
int	hashCode() Override Object.hashCode() to implement equals.
boolean	isShared() If this Dimension is shared, or is private to a Variable.
boolean	isUnlimited() If this is a NetCDF unlimited dimension.
boolean	isVariableLength() If variable length, then the length is unknown until the data is read.
static java.util.List<Dimension>	makeDimensionsAnon(int[] shape) Deprecated. use Dimensions.makeDimensionsAnon()
static java.util.List<Dimension>	makeDimensionsList(Group parentGroup, java.lang.String dimString) Deprecated. use Group.makeDimensionsList()
static java.util.List<Dimension>	makeDimensionsList(java.util.List<Dimension> dimensions, java.lang.String dimString) Deprecated. use Dimensions.makeDimensionsList()
static java.lang.String	makeDimensionsString(java.util.List<Dimension> dimensions) Deprecated. use Dimensions.makeDimensionsString()
java.lang.String	makeFullName() Deprecated. Do not use.
void	setGroup(Group g) Deprecated. Use Dimension.builder()
Dimension	setImmutable() Deprecated. Use Dimension.builder()
void	setLength(int n) Deprecated. Use Dimension.builder()
java.lang.String	setName(java.lang.String name) Deprecated. Use Dimension.builder()
void	setShared(boolean b) Deprecated. Use Dimension.builder()
void	setUnlimited(boolean b) Deprecated. Use Dimension.builder()
void	setVariableLength(boolean b) Deprecated. Use Dimension.builder()
Dimension.Builder	toBuilder() Turn into a mutable Builder, use toBuilder().build() to make a copy.
java.lang.String	toString()
java.lang.String	writeCDL(boolean strict) Deprecated. use CDLWriter

Methods inherited from class ucar.nc2.CDMNode

annotate, annotation, getDODSName, getFullName, getFullNameEscaped, getImmutable, getParentGroup, getParentStructure, getSort, isMemberOfStructure, localhash, setDODSName, setParentGroup, setParentStructure, setShortName, setSort, unwrap

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

VLEN

public static final Dimension VLEN

A variable-length dimension: the length is not known until the data is read.

Constructor Detail

Dimension

public Dimension(java.lang.String name,
                 int length)

Constructor

Parameters:

name - name must be unique within group

length - length of Dimension

Dimension

@Deprecated
public Dimension(java.lang.String name,
                             int length,
                             boolean isShared)

Deprecated. Use Dimension.builder()

Constructor

Parameters:

name - name must be unique within group

length - length, or UNLIMITED.length or UNKNOWN.length

isShared - whether its shared or local to Variable.

Dimension

public Dimension(java.lang.String name,
                 int length,
                 boolean isShared,
                 boolean isUnlimited,
                 boolean isVariableLength)

Constructor

Parameters:

name - name must be unique within group. Can be null only if not shared.

length - length, or UNLIMITED.length or UNKNOWN.length

isShared - whether its shared or local to Variable.

isUnlimited - whether the length can grow.

isVariableLength - whether the length is unknown until the data is read.

Dimension

@Deprecated
public Dimension(java.lang.String name,
                             Dimension from)

Deprecated. Use Dimension.builder()

Copy Constructor. used to make global dimensions

Parameters:

name - name must be unique within group. Can be null only if not shared.

from - copy all other fields from here.

Method Detail

makeDimensionsString

@Deprecated
public static java.lang.String makeDimensionsString(java.util.List<Dimension> dimensions)

Deprecated. use Dimensions.makeDimensionsString()

Make a space-delineated String from a list of Dimension names. Inverse of makeDimensionsList().

Returns:

space-delineated String of Dimension names.

makeDimensionsList

@Deprecated
public static java.util.List<Dimension> makeDimensionsList(Group parentGroup,
                                                                       java.lang.String dimString)
                                                                throws java.lang.IllegalArgumentException

Deprecated. use Group.makeDimensionsList()

Create a dimension list using the dimensions names. The dimension is searched for recursively in the parent groups, so it must already have been added. Inverse of makeDimensionsString().

Parameters:

parentGroup - containing group, may not be null

dimString - : whitespace separated list of dimension names, or '*' for Dimension.UNKNOWN, or number for anon dimension. null or empty String is a scalar.

Returns:

list of dimensions

Throws:

java.lang.IllegalArgumentException - if cant find dimension or parse error.

makeDimensionsList

@Deprecated
public static java.util.List<Dimension> makeDimensionsList(java.util.List<Dimension> dimensions,
                                                                       java.lang.String dimString)

Deprecated. use Dimensions.makeDimensionsList()

Create a dimension list using the dimensions names. Inverse of makeDimensionsString().

Parameters:

dimensions - list of possible dimensions, may not be null

dimString - : whitespace separated list of dimension names, or '*' for Dimension.UNKNOWN, or number for anon dimension. null or empty String is a scalar.

Returns:

list of dimensions

Throws:

java.lang.IllegalArgumentException - if cant find dimension or parse error.

makeDimensionsAnon

@Deprecated
public static java.util.List<Dimension> makeDimensionsAnon(int[] shape)

Deprecated. use Dimensions.makeDimensionsAnon()

toBuilder

public Dimension.Builder toBuilder()

Turn into a mutable Builder, use toBuilder().build() to make a copy.

getLength

public int getLength()

Get the length of the Dimension.

getName

public java.lang.String getName()

Get the name of the Dimension. Same as getShortName. Not deprecated.

Overrides:

getName in class CDMNode

getShortName

public java.lang.String getShortName()

Get the name of the Dimension.

Overrides:

getShortName in class CDMNode

isUnlimited

public boolean isUnlimited()

If this is a NetCDF unlimited dimension. The length might increase between invocations, but it remains fixed for the lifetime of the NetcdfFile. If you modify the file in a separate process, you must close and reopen the file.

Returns:

if its an "unlimited" Dimension

isVariableLength

public boolean isVariableLength()

If variable length, then the length is unknown until the data is read.

Returns:

if its a "variable length" Dimension.

isShared

public boolean isShared()

If this Dimension is shared, or is private to a Variable. All Dimensions in NetcdfFile.getDimensions() or Group.getDimensions() are shared. Dimensions in the Variable.getDimensions() may be shared or private.

Returns:

if its a "shared" Dimension.

getGroup

@Deprecated
public Group getGroup()

Deprecated. Do not use.

Get the Group that owns this Dimension.

Overrides:

getGroup in class CDMNode

Returns:

owning group or null if !isShared

makeFullName

@Deprecated
public java.lang.String makeFullName()

Deprecated. Do not use.

equals

public boolean equals(java.lang.Object oo)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Override Object.hashCode() to implement equals.

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(Dimension odim)

Dimensions with the same name are equal. This method is inconsistent with equals()!

Specified by:

compareTo in interface java.lang.Comparable<Dimension>

Parameters:

odim - compare to this Dimension

Returns:

0, 1, or -1

writeCDL

@Deprecated
public java.lang.String writeCDL(boolean strict)

Deprecated. use CDLWriter

CDL representation.

Parameters:

strict - if true, write in strict adherence to CDL definition.

Returns:

CDL representation.

setUnlimited

@Deprecated
public void setUnlimited(boolean b)

Deprecated. Use Dimension.builder()

Set whether this is unlimited, meaning length can increase.

Parameters:

b - true if unlimited

setVariableLength

@Deprecated
public void setVariableLength(boolean b)

Deprecated. Use Dimension.builder()

Set whether the length is variable.

Parameters:

b - true if variable length

setShared

@Deprecated
public void setShared(boolean b)

Deprecated. Use Dimension.builder()

Set whether this is shared.

Parameters:

b - true if shared

setLength

@Deprecated
public void setLength(int n)

Deprecated. Use Dimension.builder()

Set the Dimension length.

Parameters:

n - length of Dimension

setName

@Deprecated
public java.lang.String setName(java.lang.String name)

Deprecated. Use Dimension.builder()

Set the name, converting to valid CDM object name if needed.

Parameters:

name - set to this value

Returns:

valid CDM object name

setGroup

@Deprecated
public void setGroup(Group g)

Deprecated. Use Dimension.builder()

Set the group

Parameters:

g - parent group

setImmutable

@Deprecated
public Dimension setImmutable()

Deprecated. Use Dimension.builder()

Make this immutable.

Overrides:

setImmutable in class CDMNode

Returns:

this

builder

public static Dimension.Builder builder()

builder

public static Dimension.Builder builder(java.lang.String name,
                                        int length)

A builder with the Dimension name and length set