Package watson

Class Contact

java.lang.Object

watson.Contact

public final class Contact
extends Object

Contact class for associated CONTACTS table in database.

A Contact object contains information about a given contact. Contacts must be constructed using the Contacts class, and can be added to the database with Database.addContact().

A Contact object can be created with:

 jshell> import watson.*

 jshell> Contact c = new Contact()
 c ==> 
 

Contacts only allow particular, predefined fields. The user can see what fields are available by calling the fields() method, which returns a Set:

 jshell> c.fields()
 $3 ==> [SURNAME=varchar(40), FIRSTNAME=varchar(40), PHONE=varchar(16)]
 

In the Set above, each element is a SimpleEntry containing two Strings (or, a "key" and a "value"). The key of each element is the SQL identifier for that particular piece of contact information. The value of each element is the SQL description of that field. As this is a Set, these key-value pairs may not always be returned in the same order. To set a particular field, use the set() function:

 jshell> c.set("SURNAME", "O'Neill")
 $4 ==> (SURNAME) values ('O''Neill')
 

Field assignment can be chained, and multiple fields can be set at once (the Contact object itself is the return value):

 jshell> c.set("firstname", "Colin").set("Phone", "+353445671234")
 $5 ==> (FIRSTNAME, SURNAME, PHONE) values ('Colin', 'O''Neill', '+353445671234')
 

Note that the SQL identifiers ("Phone", "firstname", etc.) are case-insensitive, and that the apostrophe in "O'Neill" has been escaped (by doubling). Field validation and sanitisation is performed in the set() method, which is why fields must be hardcoded and cannot be added by the user. Attempting to set an invalid value to a particular field results in an error (and the unchanged Contact object is returned):

 jshell> c.set("phone", "this is not a phone number")
          ERROR | set() : phone numbers can only contain digits and '+' signs
 $6 ==> (FIRSTNAME, SURNAME, PHONE) values ('Colin', 'O''Neill', '+353445671234')
 

...as does attempting to set a value to a nonexistent field:

 jshell> c.set("email", "oneillc@fast.net")
          ERROR | keyExists() : Contact doesn't contain key 'email'
 $7 ==> (FIRSTNAME, SURNAME, PHONE) values ('Colin', 'O''Neill', '+353445671234')
 

Fields can be overwritten by simply calling set() again with a valid value, and can be removed by setting their values to null, an empty String, or an all-whitespace String:

 jshell> c.set("PhOnE", " ").set("firstNAME", "T'Challa")
 $8 ==> (FIRSTNAME, SURNAME) values ('T''Challa', 'O''Neill')
 

Field Summary

Fields

Modifier and Type	Field	Description
protected LinkedHashMap<String,Map.Entry<String,String>>	info	Information associated with this Contact object.

Constructor Summary

Constructors

Constructor	Description
Contact()

Method Summary

Modifier and Type	Method	Description
Set<Map.Entry<String,String>>	fields()	Returns a Set containing the name and SQL description of each piece of information which can be added to this Contact object.
Optional<String>	get(String key)	Returns the value associated with the key in this Contact's info, if the key exists.
boolean	keyExists(String key)	Returns true if the specified key is valid (if a Contact object allows a value associated with that key).
Contact	set(String key, String value)	If the given key exists in this Contact's info, sets it to the given value.
String	toString()	Returns this Contact formatted so that it can be inserted as a list of values into an SQL table.

Methods inherited from class java.lang.Object

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

Field Detail

info

protected LinkedHashMap<String,Map.Entry<String,String>> info

Information associated with this Contact object.

Constructor Detail

Contact

public Contact()

Method Detail

fields

public Set<Map.Entry<String,String>> fields()

Returns a Set containing the name and SQL description of each piece of information which can be added to this Contact object.

The first element of each Map.Entry is the SQL identifier for that particular piece of information (i.e. "PHONE") and the second element is the SQL description (i.e. "varchar(16)").

Returns:

a Set containing the name and SQL description of each piece of information which can be added to this Contact object.

keyExists

public boolean keyExists(String key)

Returns true if the specified key is valid (if a Contact object allows a value associated with that key).

Returns false if the key is null, empty, or all-whitespace, or if the Contact doesn't contain the specified key. Otherwise, returns true.

Parameters:

key - key to check for existence within this Contact's info

Returns:

true if the specified key is valid (if a Contact object allows a value associated with that key)

get

public Optional<String> get(String key)

Returns the value associated with the key in this Contact's info, if the key exists.

If the key doesn't exist, an empty Optional is returned. Note that keys are case-insensitive. If the key exists, but the value is null, an empty String is wrapped in an Optional and returned.

Parameters:

key - name of the value to get from this Contact's info

Returns:

the value associated with the key in this Contact's info, if the key exists

set

public Contact set(String key,
                   String value)

If the given key exists in this Contact's info, sets it to the given value.

If the key does not exist, this Contact object is returned as-is and this method throws no error. If the value is null, an empty String, or an all-whitespace String, the value associated with the key in this Contact's info will be set to null.

Parameters:

key - variable to set (must be a variable listed in info)

value - value to assign to the variable referenced by key

Returns:

this Contact, with key set to its new value (if both key and value are valid)

toString

public String toString()

Returns this Contact formatted so that it can be inserted as a list of values into an SQL table.

If all fields of this Contact are null, this method returns a null String.

Overrides:

toString in class Object

Returns:

this Contact formatted so that it can be inserted as a list of values into an SQL table