*
* @param depth
* the depth into which to descend (0 = only this object, not its
- * children)
+ * children, negative value for infinite depth)
*
* @return the debug {@link String}
*/
*
* <p>
* Not that this state is <b>lossy</b>. You cannot retrieve the data from
- * the state, it can only be used as an ID to check if thw data are
+ * the state, it can only be used as an ID to check if the data are
* identical.
* </p>
*
* Get the recursive state of the current object, i.e., its children
* included. It represents the full state information about this object's
* children.
- *
+ * <p>
* It is not hashed.
*
* @param builder
*
* @param depth
* the depth into which to descend (0 = only this object, not its
- * children)
+ * children, negative value for infinite depth)
*
* @param tab
* the current tabulation increment
builder.append(" ");
builder.append(getContentState(false) + " " + getId());
- if (depth > 0)
+ if (depth != 0)
builder.append(": [");
- if (depth > 0) {
+ if (depth != 0) {
for (E child : this) {
builder.append("\n");
child.getDebugInfo(builder, depth - 1, tab + 1);
}
}
- if (depth > 0) {
+ if (depth != 0) {
builder.append("\n");
for (int i = 0; i < tab; i++)
builder.append(" ");
}
/**
- * Notify that this element has unsaved changes.
+ * Notify that this element <i>and all its parent elements</i> has unsaved
+ * changes.
*/
void setDirty() {
dirty = true;
}
/**
- * Set the parent of this element <i>and all its descendants</i>.
+ * Set the parent of this element.
+ * <p>
+ * Will also check and fix if needed the parent (this) of all its
+ * descendants (recursively).
*
* @param parent
* the new parent
* contacts.
*
* @author niki
- *
*/
public class Card extends BaseClass<Contact> {
private File file;
return false;
BufferedWriter writer = new BufferedWriter(new FileWriter(file));
- Parser.write(writer, format, this);
- writer.close();
+ try {
+ Parser.write(writer, format, this);
+ } finally {
+ writer.close();
+ }
if (this.file != null
&& file.getCanonicalPath().equals(this.file.getCanonicalPath())) {
/**
* A contact is the information that represent a contact person or organisation.
+ * <p>
+ * Each {@link Data} inside can be binary encoded or not: if it is binary
+ * encoded, it has an active BKey number (not -1) associated to it (of value 0
+ * if still not sorted, or unique for the whole {@link Contact} if already
+ * processed).
*
* @author niki
- *
*/
public class Contact extends BaseClass<Data> {
private int nextBKey = 1;
/**
* Return the value of the preferred data field with this name, or NULL if
- * none (you cannot differentiate a NULL value and no value).
+ * none (you cannot differentiate a NULL value and no value with this method
+ * -- for that, check {@link Contact#getPreferredData(String)}).
*
* @param name
* the name to look for
* Get the Data fields that share the given name.
*
* @param name
- * the name to ook for
+ * the name to look for
* @return a list of Data fields with this name
*/
public List<Data> getData(String name) {
}
/**
- * Return a {@link String} representation of this contact, in vCard 2.1,
- * without BKeys.
+ * Return a simple {@link String} representation of this contact without
+ * BKeys.
*
* @return the {@link String} representation
*/
/**
* Add a {@link String} to the given {@link List}, but make sure it does not
* exceed the maximum size, and truncate it if needed to fit.
+ * <p>
+ * Will always add one and only one {@link String} (potentially empty) at
+ * the end of <tt>list</tt>.
*
* @param list
+ * the list to add to
* @param add
+ * the {@link String} to (either fully or partially) add
* @param currentSize
+ * the current total size (managed outside of this method)
* @param maxSize
- * @return
+ * the maximum size that cannot be exceeded (or -1 for
+ * "no maximum") -- if the maximum size would be exceeded by
+ * adding this {@link String}, only a part of it will be added;
+ * if the maximum size is already reached or exceeded (should not
+ * happen because of this method), an empty {@link String} will
+ * be added
+ *
+ * @return the number of characters added (the size of the last
+ * {@link String} in <tt>list</tt>)
*/
static private int addToList(List<String> list, String add,
int currentSize, int maxSize) {
import java.util.List;
/**
- * A data is a piece of information present in a {@link Contact}. It is
+ * A {@link Data} is a piece of information present in a {@link Contact}. It is
* basically a key/value pair with optional types and an optional group name.
+ * <p>
+ * A {@link Data} can also be binary encoded: in this case, it has an associated
+ * BKey number to identify it.
*
* @author niki
- *
*/
public class Data extends BaseClass<TypeInfo> {
public enum DataPart {
FN_FAMILY, FN_GIVEN, FN_ADDITIONAL, // Name
FN_PRE, FN_POST, // Pre/Post
BDAY_YYYY, BDAY_MM, BDAY_DD, // BDay
+ // Address:
ADR_PBOX, ADR_EXTENDED, ADR_STREET, ADR_CITY, ADR_REGION, ADR_POSTAL_CODE, ADR_COUNTRY
- // Address
}
private String name;
/**
* Return the bkey number of this {@link Data} or -1 if it is not binary.
+ * <p>
+ * For binary data, as long as the BKey is not processed, it will be 0.
*
- * @return the bkey or -1
+ * @return the bkey, 0 or -1
*/
public int getB64Key() {
return b64;
}
/**
- * Check if this {@link Data} is binary
+ * Check if this {@link Data} is binary (in this case, the BKey will be
+ * present).
*
* @return TRUE if it is
*/
/**
* Return the {@link List} of sep-listed values from this {@link String}
* data.
+ * <p>
+ * Will take the backslash character into account (i.e., a backslash can
+ * escape the given separator).
*
* @param value
* the data
* This class describes a type, that is, a key-value pair.
*
* @author niki
- *
*/
public class TypeInfo extends BaseClass<TypeInfo> {
private String name;
git://git.nikiroo.be / jvcard.git / commitdiff