com.conveyal.gtfs.loader

Class Field

java.lang.Object

com.conveyal.gtfs.loader.Field

Direct Known Subclasses:

BooleanField, ColorField, CurrencyField, DateField, DateListField, DoubleField, IntegerField, LanguageField, ShortField, StringField, StringListField, TimeField, URLField

public abstract class Field
extends Object

Field subclasses process an incoming String that represents a single GTFS CSV field value. The value is validated and converted to its final format. We need to propagate any validation errors up to the caller (where file, line, and column number context are known), Unfortunately Java does not allow multiple return values. There are multiple options. We could emulate multiple return by wrapping the resulting String in another object that combines it with an error type. We could pass a list into every function and the functions could add errors to that list. We could make the Field instances have state, which will also make them single-use and single-thread. They could then accumulate errors as they do their work. We could return an error or list of errors from functions that store the validated value into an array passed in as a parameter. In all cases, to avoid enormous amounts of useless object creation we could re-use error lists and just clear them before each validation operation. However, within the Field implementations, we may need to call private/internal functions that also return multiple values (an error and a modified value).

Field Summary

Fields

Modifier and Type	Field and Description
static Set<IllegalCharacter>	ILLEGAL_CHARACTERS Keep any illegal character sequences and their respective replacements here.
String	name
Table	referenceTable Indicates that this field acts as a foreign key to this referenced table.
Requirement	requirement

Constructor Summary

Constructors

Constructor and Description
Field(String name, Requirement requirement)

Method Summary

Modifier and Type	Method and Description
protected static ValidateFieldResult<String>	cleanString(String string)
protected static ValidateFieldResult<String>	cleanString(ValidateFieldResult<String> previousResult)
String	getColumnExpression(String prefix, boolean csvOutput) Get the expression used to select this column from the database based on the prefix.
static int	getFieldIndex(Field[] fields, String name) Finds the index of the field given a string name.
String	getSqlDeclaration()
abstract SQLType	getSqlType()
String	getSqlTypeName()
Field	indexThisColumn() Fluent method that indicates that a newly constructed field should be indexed after the table is loaded.
boolean	isEmptyValuePermitted() Check if empty values are permitted for this field.
boolean	isForeignReference() More than one foreign reference should not be created on the same table to the same foreign table.
Field	isReferenceTo(Table table) Fluent method indicates that this field is a reference to an entry in the table provided as an argument.
boolean	isRequired()
boolean	missingRequired(String string) Generally any required field should be present on every row.
Field	permitEmptyValue() Fluent method to permit empty values for this field.
void	setNull(PreparedStatement preparedStatement, int oneBasedIndex)
abstract Set<NewGTFSError>	setParameter(PreparedStatement preparedStatement, int oneBasedIndex, String string)
boolean	shouldBeIndexed()
abstract ValidateFieldResult<String>	validateAndConvert(String original) Check the supplied string to see if it can be parsed as the proper data type.

Methods inherited from class java.lang.Object

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

Field Detail

name

public final String name

ILLEGAL_CHARACTERS

public static final Set<IllegalCharacter> ILLEGAL_CHARACTERS

Keep any illegal character sequences and their respective replacements here. TODO: Add other illegal character sequences (e.g., HTML tags, comments or escape sequences).

requirement

public final Requirement requirement

referenceTable

public Table referenceTable

Indicates that this field acts as a foreign key to this referenced table. This is used when checking referential integrity when loading a feed.

Constructor Detail

Field

public Field(String name,
             Requirement requirement)

Method Detail

validateAndConvert

public abstract ValidateFieldResult<String> validateAndConvert(String original)

Check the supplied string to see if it can be parsed as the proper data type. Perform any conversion (I think this is only done for times, to integer numbers of seconds). TODO should we really be converting times and dates to numbers or storing them as strings to simplify things?

Parameters:

original - a non-null String

Returns:

a string that is parseable as this field's type, or null if it is not parseable

setParameter

public abstract Set<NewGTFSError> setParameter(PreparedStatement preparedStatement,
                                               int oneBasedIndex,
                                               String string)

setNull

public void setNull(PreparedStatement preparedStatement,
                    int oneBasedIndex)
             throws SQLException

Throws:

SQLException

getFieldIndex

public static int getFieldIndex(Field[] fields,
                                String name)

Finds the index of the field given a string name.

Returns:

the index of the field or -1 if no match is found

getSqlType

public abstract SQLType getSqlType()

getSqlTypeName

public String getSqlTypeName()

getSqlDeclaration

public String getSqlDeclaration()

cleanString

protected static ValidateFieldResult<String> cleanString(String string)

cleanString

protected static ValidateFieldResult<String> cleanString(ValidateFieldResult<String> previousResult)

missingRequired

public boolean missingRequired(String string)

Generally any required field should be present on every row. TODO override this method for exceptions, e.g. arrival and departure can be missing though the field must be present

isRequired

public boolean isRequired()

isForeignReference

public boolean isForeignReference()

More than one foreign reference should not be created on the same table to the same foreign table. This is what allows us to embed updates to a sub-table in nested JSON because this creates a many-to-one reference instead of a many-to-many reference.

indexThisColumn

public Field indexThisColumn()

Fluent method that indicates that a newly constructed field should be indexed after the table is loaded. FIXME: should shouldBeIndexed be determined based on presence of referenceTable?

Returns:

this same Field instance, which allows constructing and assigning the instance in the same statement.

shouldBeIndexed

public boolean shouldBeIndexed()

isReferenceTo

public Field isReferenceTo(Table table)

Fluent method indicates that this field is a reference to an entry in the table provided as an argument.

Parameters:

table -

Returns:

this same Field instance

permitEmptyValue

public Field permitEmptyValue()

Fluent method to permit empty values for this field. Used for cases like fare_attributes#transfers, where empty values are OK on a required field.

Returns:

this same Field instance, which allows constructing and assigning the instance in the same statement.

isEmptyValuePermitted

public boolean isEmptyValuePermitted()

Check if empty values are permitted for this field.

getColumnExpression

public String getColumnExpression(String prefix,
                                  boolean csvOutput)

Get the expression used to select this column from the database based on the prefix. The csvOutput parameter is needed in overriden method implementations that have special ways of outputting certain fields. The prefix parameter is assumed to be either null or a string in the format: `schema.`