ucar.unidata.data
Class DataCategory

java.lang.Object
  ucar.unidata.data.DataCategory

public class DataCategory
extends Object

This represents a hierarchical category of string names and is used to categorize different flavors of data within DataChoice objects and for determining what displays are applicable to what data. A DataCategory object really represents a node in a list of DataCategory objects that define the hierarchy. For example, the string FOO-BAR-ZOO is represented by three DataCategory objects:

 +-----+     +-----+     +-----+
 | FOO |-->  | BAR | --> | ZOO |
 +-----+     +-----+     +-----+
 

There are static utility methods for parsing a string category name into a chain of objects. Likewise there are methods for parsing a String of semi-colon delimited category strings into a Collection of DataCategory chains.

Category names can also hold regular expressions,e.g., "*", "+" and "." that gives us alot of flexibility in creating categories that match a variety of flavors of data.

Version:

$Revision: 1.74 $

Author:

IDV development team

Field Summary

static String	ATTR_DESC The description attribute (for XML)
static String	ATTR_NAME The name attribute (for XML)
static String	CATEGORY_2D The 2D category
static String	CATEGORY_3D The 3D category
static String	CATEGORY_ANY The category that matches any other category
static String	CATEGORY_COSMICSKEWT The track skew-T category @deprecated use TRACK_SOUNDING
static String	CATEGORY_DISPLAY The display category
static String	CATEGORY_ENSEMBLE The grid ensemble category
static String	CATEGORY_GRID The grid category
static String	CATEGORY_GRIDSKEWT The grid skew-T category @deprecated use GRID_SOUNDING
static String	CATEGORY_GRIDSOUNDING The grid skew-T category
static String	CATEGORY_HTML The html category
static String	CATEGORY_IMAGE The image category
static String	CATEGORY_POINT The point category
static String	CATEGORY_POINTPLOT The stationplot category
static String	CATEGORY_PROFILER_3D The profiler 3D category
static String	CATEGORY_PROFILER_MULTISTA The multi station profiler category
static String	CATEGORY_PROFILER_ONESTA The one station profiler category
static String	CATEGORY_PROFILER_PLAN The profiler plan view category
static String	CATEGORY_RAOB The RAOB category
static String	CATEGORY_RAOBSKEWT The RAOB skew-T category @deprecated use RAOB_SOUNDING
static String	CATEGORY_RAOBSOUNDING The RAOB skew-T category
static String	CATEGORY_SKEWT The Skew-T category
static String	CATEGORY_SOUNDING The Sounding category
static String	CATEGORY_TEXT The text category
static String	CATEGORY_TRACK The track category
static String	CATEGORY_TRACKSKEWT The track skew-T category @deprecated use TRACK_SOUNDING
static String	CATEGORY_TRACKSOUNDING The track skew-T category
static String	CATEGORY_TRAJECTORYSOUNDING The track skew-T category
static String	CATEGORY_VISAD The VisAD category
protected DataCategory	child child of thie DataCategory
static DataCategory	COSMIC_SKEWT_CATEGORY _more_
static String	DIVIDER Identifier for a category divider
static DataCategory	ENSEMBLE_CATEGORY grid ensemble categories
static DataCategory	GRID_3D_SKEWT_CATEGORY Deprecated. use #GRID_3D_SOUNDING_CATEGORY
static DataCategory	GRID_3D_SOUNDING_CATEGORY Grid-derived data appropriate for an aerological sounding display (DateTime -> (EarthLocationTuple -> (AirTemperature, DewPoint))).
static DataCategory	LOCATIONS_CATEGORY Category for locations
protected String	name name of this DataCategory
static DataCategory	NONE_CATEGORY Category to use for none.
static DataCategory	NULL NULL category
static DataCategory	POINT_PLOT_CATEGORY Point Plot Category
static DataCategory	PROFILER_ONESTA_CATEGORY Profiler data appropriate for a one station time-hgt display
static DataCategory	PROFILER_PLAN_CATEGORY Profiler data appropriate for multi-staiton plan view of winds at hgt;
static DataCategory	RAOB_SKEWT_CATEGORY RAOB-derived data appropriate for a Skew-T display (DateTime, EarthLocationTuple, InSituAirTemperatureProfile, DewPointProfile).
static DataCategory	RAOB_SOUNDING_CATEGORY RAOB-derived data appropriate for a sounding display (DateTime, EarthLocationTuple, InSituAirTemperatureProfile, DewPointProfile).
static String	TAG_CATEGORIES An id for a set of categories
static String	TAG_CATEGORY An id for a single category
static DataCategory	TRACK_SKEWT_CATEGORY Deprecated. use #TRACK_SOUNDING_CATEGORY
static DataCategory	TRACK_SOUNDING_CATEGORY Track-derived data appropriate for an aerological sounding display (DateTime -> (Pressure, Temperature, DewPoint, PolarHorizontalWind, EarthLocationTuple)).
static DataCategory	TRAJECTORY_SOUNDING_CATEGORY Category for the trajectory feature type data files
static DataCategory	XGRF_CATEGORY Category for the drawing files

Constructor Summary

DataCategory()
Default constructor.

DataCategory(boolean forDisplay)
ctor

DataCategory(DataCategory parent, String name)
Create a category with given parent category and name.

DataCategory(String name)
Create a parent-less category with the given name.

DataCategory(String name, boolean forDisplay)
Create a parent-less category with the given forDisplay state

DataCategory(String name, DataCategory metaCategory)
Create a parent-less category with the given metacategory.

DataCategory(String name, List metaCategories)
Create a parent-less category with the given metacategories.

Method Summary

static void	addCurrentCategory(String c) Add the category into the global list
boolean	applicableTo(DataCategory d) Check to see if this object is applicable to the given DataCategory argument.
boolean	applicableTo(List dcs) Go through the list of DataCategory objects.
static boolean	applicableTo(List from, List to) Return whether any of the DataCategory's in from are applicable to the list in to.
DataCategory	copyAndAppend(String append) Append the string to the data category and return a new category.
static DataCategory	createCategory(String n1) Helper method to instantiate a single category
static DataCategory	createCategory(String[] names) Create a DataCategory from the array of names.
static DataCategory	createCategory(String n1, String n2) Helper method to instantiate two categories
static DataCategory	createCategory(String n1, String n2, String n3) Helper method to instantiate a three categories
static DataCategory	createCategory(String n1, String n2, String n3, String n4) Helper method to instantiate a four categories
boolean	equals(Object o) See if this DataCategory is equivalent to another
String	getAppend() Get the appended category string (used by XML persistence)
int	getCategoryIndex() Get the category index (used by XML persistence)
DataCategory	getChild() Return the child category of this object.
int	getChildIndex() Get the child index (used by XML persistence)
static List	getCurrentCategories() Get all current category strings
boolean	getForDisplay() Get the "for display" property.
String	getFullName() Return the full path of this category with its child Use the default DIVIDER as the string divider between sub categories.
String	getFullName(String divider) Return the full path of this category with its child Use the given argument as the string divider between sub categories.
String	getFullName(String prefix, String suffix) Return the full path of this category with its child Use the given arguments as the string divider between sub categories.
List	getMetaCategories() Get the list of meta categories for this DataCategory
String	getName() Return the name of this category
protected String	getPattern() Return the regular expression that this DataCategory represents It is somewhat tricky because the parent category might have been none (i.e., "*" or if this is the topmost category)
String	getReplace() Get the Replace property.
boolean	hasCategory() Check if this DataCategory has a meta category.
int	hashCode() Return the hashcode for this DataCategory
static void	init(XmlResourceCollection resources) Used by XML persistence initialization.
boolean	isInherited() See if this is an inherited category
static void	main(String[] args) Method for testing this class.
static boolean	matchRegexp(String source, String pattern) Deprecated. use ucar.unidata.util.StringUtil.stringMatch(String, String) instead
static List	parseCategories(String c) Parse out a string of semi-colon delimited categories e.g.: "catname1-catname2-catnameN;othercategory1-othercategory2;..."
static List	parseCategories(String c, boolean firstOneForDisplay) Parse out a string of semi-colon delimited categories e.g.: "catname1-catname2-catnameN;othercategory1-othercategory2;..."
static DataCategory	parseCategory(String c, boolean forDisplay) Parse out a string of the form "catname1-catname2-catnameN" and return a chain of category objects representing catname1->catname2->catnameN.
void	setAppend(String value) Set the appended category string (used by XML persistence)
void	setCategoryIndex(int value) Set the category index (used by XML persistence)
void	setChild(DataCategory child) Sets the child member of this category.
void	setChildIndex(int value) Set the child index (used by XML persistence)
void	setForDisplay(boolean value) Set the "for display" property.
void	setName(String n) Set the name property.
void	setReplace(String value) Set the Replace property.
String	toString() Return a String representation of this DataCategory
String	toString(String divider) Return a String representation of this DataCategory using the given divider

Methods inherited from class java.lang.Object

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

Field Detail

NULL

public static final DataCategory NULL

NULL category

DIVIDER

public static final String DIVIDER

Identifier for a category divider

See Also:

Constant Field Values

name

protected String name

name of this DataCategory

child

protected DataCategory child

child of thie DataCategory

CATEGORY_ANY

public static final String CATEGORY_ANY

The category that matches any other category

See Also:

Constant Field Values

CATEGORY_TEXT

public static final String CATEGORY_TEXT

The text category

See Also:

Constant Field Values

CATEGORY_HTML

public static final String CATEGORY_HTML

The html category

See Also:

Constant Field Values

CATEGORY_DISPLAY

public static final String CATEGORY_DISPLAY

The display category

See Also:

Constant Field Values

CATEGORY_GRID

public static final String CATEGORY_GRID

The grid category

See Also:

Constant Field Values

CATEGORY_POINT

public static final String CATEGORY_POINT

The point category

See Also:

Constant Field Values

CATEGORY_VISAD

public static final String CATEGORY_VISAD

The VisAD category

See Also:

Constant Field Values

CATEGORY_IMAGE

public static final String CATEGORY_IMAGE

The image category

See Also:

Constant Field Values

CATEGORY_3D

public static final String CATEGORY_3D

The 3D category

See Also:

Constant Field Values

CATEGORY_2D

public static final String CATEGORY_2D

The 2D category

See Also:

Constant Field Values

CATEGORY_RAOB

public static final String CATEGORY_RAOB

The RAOB category

See Also:

Constant Field Values

CATEGORY_SKEWT

public static final String CATEGORY_SKEWT

The Skew-T category

See Also:

Constant Field Values

CATEGORY_SOUNDING

public static final String CATEGORY_SOUNDING

The Sounding category

See Also:

Constant Field Values

CATEGORY_POINTPLOT

public static final String CATEGORY_POINTPLOT

The stationplot category

See Also:

Constant Field Values

CATEGORY_TRACK

public static final String CATEGORY_TRACK

The track category

See Also:

Constant Field Values

CATEGORY_GRIDSKEWT

public static final String CATEGORY_GRIDSKEWT

The grid skew-T category @deprecated use GRID_SOUNDING

See Also:

Constant Field Values

CATEGORY_RAOBSKEWT

public static final String CATEGORY_RAOBSKEWT

The RAOB skew-T category @deprecated use RAOB_SOUNDING

See Also:

Constant Field Values

CATEGORY_TRACKSKEWT

public static final String CATEGORY_TRACKSKEWT

The track skew-T category @deprecated use TRACK_SOUNDING

See Also:

Constant Field Values

CATEGORY_COSMICSKEWT

public static final String CATEGORY_COSMICSKEWT

The track skew-T category @deprecated use TRACK_SOUNDING

See Also:

Constant Field Values

CATEGORY_GRIDSOUNDING

public static final String CATEGORY_GRIDSOUNDING

The grid skew-T category

See Also:

Constant Field Values

CATEGORY_ENSEMBLE

public static final String CATEGORY_ENSEMBLE

The grid ensemble category

See Also:

Constant Field Values

CATEGORY_RAOBSOUNDING

public static final String CATEGORY_RAOBSOUNDING

The RAOB skew-T category

See Also:

Constant Field Values

CATEGORY_TRACKSOUNDING

public static final String CATEGORY_TRACKSOUNDING

The track skew-T category

See Also:

Constant Field Values

CATEGORY_TRAJECTORYSOUNDING

public static final String CATEGORY_TRAJECTORYSOUNDING

The track skew-T category

See Also:

Constant Field Values

CATEGORY_PROFILER_ONESTA

public static final String CATEGORY_PROFILER_ONESTA

The one station profiler category

See Also:

Constant Field Values

CATEGORY_PROFILER_MULTISTA

public static final String CATEGORY_PROFILER_MULTISTA

The multi station profiler category

See Also:

Constant Field Values

CATEGORY_PROFILER_PLAN

public static final String CATEGORY_PROFILER_PLAN

The profiler plan view category

See Also:

Constant Field Values

CATEGORY_PROFILER_3D

public static final String CATEGORY_PROFILER_3D

The profiler 3D category

See Also:

Constant Field Values

NONE_CATEGORY

public static final DataCategory NONE_CATEGORY

Category to use for none. Use this, for example, in a CompositeDataChoice that really has no data and is just used as a container.

RAOB_SKEWT_CATEGORY

public static final DataCategory RAOB_SKEWT_CATEGORY

RAOB-derived data appropriate for a Skew-T display (DateTime, EarthLocationTuple, InSituAirTemperatureProfile, DewPointProfile).

RAOB_SOUNDING_CATEGORY

public static final DataCategory RAOB_SOUNDING_CATEGORY

RAOB-derived data appropriate for a sounding display (DateTime, EarthLocationTuple, InSituAirTemperatureProfile, DewPointProfile).

PROFILER_ONESTA_CATEGORY

public static final DataCategory PROFILER_ONESTA_CATEGORY

Profiler data appropriate for a one station time-hgt display

PROFILER_PLAN_CATEGORY

public static final DataCategory PROFILER_PLAN_CATEGORY

Profiler data appropriate for multi-staiton plan view of winds at hgt;

GRID_3D_SKEWT_CATEGORY

public static final DataCategory GRID_3D_SKEWT_CATEGORY

Deprecated. use #GRID_3D_SOUNDING_CATEGORY

Grid-derived data appropriate for a Skew-T display (DateTime -> (EarthLocationTuple -> (AirTemperature, DewPoint))).

TRACK_SKEWT_CATEGORY

public static final DataCategory TRACK_SKEWT_CATEGORY

Deprecated. use #TRACK_SOUNDING_CATEGORY

Track-derived data appropriate for a Skew-T display (DateTime -> (Pressure, Temperature, DewPoint, PolarHorizontalWind, EarthLocationTuple)).

COSMIC_SKEWT_CATEGORY

public static final DataCategory COSMIC_SKEWT_CATEGORY

_more_

ENSEMBLE_CATEGORY

public static final DataCategory ENSEMBLE_CATEGORY

grid ensemble categories

GRID_3D_SOUNDING_CATEGORY

public static final DataCategory GRID_3D_SOUNDING_CATEGORY

Grid-derived data appropriate for an aerological sounding display (DateTime -> (EarthLocationTuple -> (AirTemperature, DewPoint))).

TRACK_SOUNDING_CATEGORY

public static final DataCategory TRACK_SOUNDING_CATEGORY

Track-derived data appropriate for an aerological sounding display (DateTime -> (Pressure, Temperature, DewPoint, PolarHorizontalWind, EarthLocationTuple)).

TRAJECTORY_SOUNDING_CATEGORY

public static final DataCategory TRAJECTORY_SOUNDING_CATEGORY

Category for the trajectory feature type data files

XGRF_CATEGORY

public static final DataCategory XGRF_CATEGORY

Category for the drawing files

LOCATIONS_CATEGORY

public static final DataCategory LOCATIONS_CATEGORY

Category for locations

POINT_PLOT_CATEGORY

public static final DataCategory POINT_PLOT_CATEGORY

Point Plot Category

TAG_CATEGORIES

public static final String TAG_CATEGORIES

An id for a set of categories

See Also:

Constant Field Values

TAG_CATEGORY

public static final String TAG_CATEGORY

An id for a single category

See Also:

Constant Field Values

ATTR_NAME

public static final String ATTR_NAME

The name attribute (for XML)

See Also:

Constant Field Values

ATTR_DESC

public static final String ATTR_DESC

The description attribute (for XML)

See Also:

Constant Field Values

Constructor Detail

DataCategory

public DataCategory()

Default constructor.

DataCategory

public DataCategory(boolean forDisplay)

ctor

Parameters:

forDisplay - Is this category a display category

DataCategory

public DataCategory(String name)

Create a parent-less category with the given name.

Parameters:

name - name of this DataCategory.

DataCategory

public DataCategory(String name,
                    boolean forDisplay)

Create a parent-less category with the given forDisplay state

Parameters:

name - name of this DataCategory

forDisplay - true if this should be displayed

DataCategory

public DataCategory(String name,
                    List metaCategories)

Create a parent-less category with the given metacategories.

Parameters:

name - name of this DataCategory

metaCategories - list of meta categories

DataCategory

public DataCategory(String name,
                    DataCategory metaCategory)

Create a parent-less category with the given metacategory.

Parameters:

name - name of this DataCategory

metaCategory - meta category

DataCategory

public DataCategory(DataCategory parent,
                    String name)

Create a category with given parent category and name. Add the new category to the parent.

Parameters:

parent - parent category

name - name of this sub category

Method Detail

hasCategory

public boolean hasCategory()

Check if this DataCategory has a meta category.

Returns:

true if it has a metacategory

getMetaCategories

public List getMetaCategories()

Get the list of meta categories for this DataCategory

Returns:

list of meta categories

init

public static void init(XmlResourceCollection resources)

Used by XML persistence initialization.

Parameters:

resources - collection of XML resources

addCurrentCategory

public static void addCurrentCategory(String c)

Add the category into the global list

Parameters:

c - category

getCurrentCategories

public static List getCurrentCategories()

Get all current category strings

Returns:

List of category strings

parseCategory

public static DataCategory parseCategory(String c,
                                         boolean forDisplay)

Parse out a string of the form "catname1-catname2-catnameN" and return a chain of category objects representing catname1->catname2->catnameN. The category objects will have their forDisplay flag set to the given value.

Parameters:

c - string of categories

forDisplay - true if the first is for display only

Returns:

new DataCategory

parseCategories

public static List parseCategories(String c)

Parse out a string of semi-colon delimited categories e.g.: "catname1-catname2-catnameN;othercategory1-othercategory2;..."

Parameters:

c - semi-colon delimeted String of categories

Returns:

list of categories

parseCategories

public static List parseCategories(String c,
                                   boolean firstOneForDisplay)

Parse out a string of semi-colon delimited categories e.g.: "catname1-catname2-catnameN;othercategory1-othercategory2;..."

Parameters:

c - semi-colon delimeted String of categories

firstOneForDisplay - true if the first one is for display only

Returns:

list of categories

createCategory

public static DataCategory createCategory(String[] names)

Create a DataCategory from the array of names. This is a hierarchical list.

Parameters:

names - array of category names

Returns:

associated DataCategory

createCategory

public static DataCategory createCategory(String n1)

Helper method to instantiate a single category

Parameters:

n1 - name of the category

Returns:

DataCategory with name n1

createCategory

public static DataCategory createCategory(String n1,
                                          String n2)

Helper method to instantiate two categories

Parameters:

n1 - name of the category

n2 - name of the child of n1

Returns:

DataCategory with one child

createCategory

public static DataCategory createCategory(String n1,
                                          String n2,
                                          String n3)

Helper method to instantiate a three categories

Parameters:

n1 - name of the category

n2 - name of the child of n1

n3 - name of the child of n2

Returns:

DataCategory with a child with a child

createCategory

public static DataCategory createCategory(String n1,
                                          String n2,
                                          String n3,
                                          String n4)

Helper method to instantiate a four categories

Parameters:

n1 - name of the category

n2 - name of the child of n1

n3 - name of the child of n2

n4 - name of the child of n3

Returns:

DataCategory with a child with a child with a child

getChild

public DataCategory getChild()

Return the child category of this object. Note: this can be null.

Returns:

child or null if none.

setChild

public void setChild(DataCategory child)

Sets the child member of this category. DataCategories are a single linear chain of objects, thus we only have one child (and one parent)

Parameters:

child - child category for this

getName

public String getName()

Return the name of this category

Returns:

category name

setName

public void setName(String n)

Set the name property. Used by XML persistence

Parameters:

n - name

isInherited

public boolean isInherited()

See if this is an inherited category

Returns:

true if inherited

getFullName

public String getFullName()

Return the full path of this category with its child Use the default DIVIDER as the string divider between sub categories.

Returns:

the full name of this category (e.g. -foo-)

getFullName

public String getFullName(String divider)

Return the full path of this category with its child Use the given argument as the string divider between sub categories.

Parameters:

divider - divider character

Returns:

full name using divider

getFullName

public String getFullName(String prefix,
                          String suffix)

Return the full path of this category with its child Use the given arguments as the string divider between sub categories.

Parameters:

prefix - prefix divider

suffix - suffix divider

Returns:

full name with dividers

getPattern

protected String getPattern()

Return the regular expression that this DataCategory represents It is somewhat tricky because the parent category might have been none (i.e., "*" or if this is the topmost category)

Returns:

regular expression pattern for this category

toString

public String toString()

Return a String representation of this DataCategory

Overrides:

toString in class Object

Returns:

string representation of this

toString

public String toString(String divider)

Return a String representation of this DataCategory using the given divider

Parameters:

divider - The divider to use between sub-categories.

Returns:

string representation of this

applicableTo

public boolean applicableTo(List dcs)

Go through the list of DataCategory objects. If this object is applicable to any of them return true. If the list is empty then return true.

Parameters:

dcs - list of DataCategories

Returns:

true if this DataCategory is applicable to any of them

applicableTo

public boolean applicableTo(DataCategory d)

Check to see if this object is applicable to the given DataCategory argument. The definition of applicability is that this data category is hierarchically a "base-class" hierachy of the given argument. There is a slight twist though: A data category can have a sub-component that represents a regular expression, i.e., :

  "*" represents 0 or more sub-categories,
  "+" represents one or more sub-categories
  "." represents one sub-category
  

Here are some examples:

This	Argument	applicableTo
"FOO-BAR"	"FOO-BAR"	true
"FOO-BAR-ZOO"	"FOO-BAR"	false
"FOO-BAR-ZOO"	"FOO-BAR"	false
"FOO-BAR-*"	"FOO-BAR"	true
"FOO-BAR-+"	"FOO-BAR"	false
"FOO-."	"FOO-BAR"	true
"FOO-.-*"	"FOO-BAR"	true
"*"	"FOO-BAR"	true
".-.-*"	"FOO-BAR"	true

Parameters:

d - DataCategory to check

Returns:

true if applicable to d

setForDisplay

public void setForDisplay(boolean value)

Set the "for display" property. (used by XML persistence)

Parameters:

value - for display property

getForDisplay

public boolean getForDisplay()

Get the "for display" property. (used by XML persistence)

Returns:

the for display property

applicableTo

public static boolean applicableTo(List from,
                                   List to)

Return whether any of the DataCategory's in from are applicable to the list in to.

Parameters:

from - List of DataCategories to check

to - List of categories that from may be applicable to.

Returns:

true if any of the from list is applicable to the to list.

See Also:

applicableTo(List)

equals

public boolean equals(Object o)

See if this DataCategory is equivalent to another

Overrides:

equals in class Object

Parameters:

o - other category

Returns:

true if o is a DataCategory and they have the same full name.

hashCode

public int hashCode()

Return the hashcode for this DataCategory

Overrides:

hashCode in class Object

Returns:

hash code

main

public static void main(String[] args)

Method for testing this class.

Parameters:

args - category string

matchRegexp

public static boolean matchRegexp(String source,
                                  String pattern)

Deprecated. use ucar.unidata.util.StringUtil.stringMatch(String, String) instead

See if a String is a match for a pattern

Parameters:

source - source string

pattern - regular expression pattern

Returns:

true if there is a match

setCategoryIndex

public void setCategoryIndex(int value)

Set the category index (used by XML persistence)

Parameters:

value - the index

getCategoryIndex

public int getCategoryIndex()

Get the category index (used by XML persistence)

Returns:

the category index

setChildIndex

public void setChildIndex(int value)

Set the child index (used by XML persistence)

Parameters:

value - the child index

getChildIndex

public int getChildIndex()

Get the child index (used by XML persistence)

Returns:

child index

setAppend

public void setAppend(String value)

Set the appended category string (used by XML persistence)

Parameters:

value - append value

getAppend

public String getAppend()

Get the appended category string (used by XML persistence)

Returns:

appended category string

setReplace

public void setReplace(String value)

Set the Replace property.

Parameters:

value - The new value for Replace

getReplace

public String getReplace()

Get the Replace property.

Returns:

The Replace

copyAndAppend

public DataCategory copyAndAppend(String append)

Append the string to the data category and return a new category.

Parameters:

append - category string to append (may be null)

Returns:

The new data category