From f04a32e97c847d7e2551037a4d5f6a070879215c Mon Sep 17 00:00:00 2001 From: Niki Roo Date: Thu, 27 Sep 2018 09:15:57 +0200 Subject: [PATCH] jDoc, possible leak on crash, new depth option --- src/be/nikiroo/jvcard/BaseClass.java | 22 ++++++++++++-------- src/be/nikiroo/jvcard/Card.java | 8 ++++--- src/be/nikiroo/jvcard/Contact.java | 31 ++++++++++++++++++++++------ src/be/nikiroo/jvcard/Data.java | 18 +++++++++++----- src/be/nikiroo/jvcard/TypeInfo.java | 1 - 5 files changed, 56 insertions(+), 24 deletions(-) diff --git a/src/be/nikiroo/jvcard/BaseClass.java b/src/be/nikiroo/jvcard/BaseClass.java index 9533321..42d4b0d 100644 --- a/src/be/nikiroo/jvcard/BaseClass.java +++ b/src/be/nikiroo/jvcard/BaseClass.java @@ -307,7 +307,7 @@ public abstract class BaseClass> implements List { * * @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} */ @@ -333,7 +333,7 @@ public abstract class BaseClass> implements List { * *

* Not that this state is lossy. 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. *

* @@ -346,7 +346,7 @@ public abstract class BaseClass> implements List { * Get the recursive state of the current object, i.e., its children * included. It represents the full state information about this object's * children. - * + *

* It is not hashed. * * @param builder @@ -372,7 +372,7 @@ public abstract class BaseClass> implements List { * * @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 @@ -382,16 +382,16 @@ public abstract class BaseClass> implements List { 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(" "); @@ -400,7 +400,8 @@ public abstract class BaseClass> implements List { } /** - * Notify that this element has unsaved changes. + * Notify that this element and all its parent elements has unsaved + * changes. */ void setDirty() { dirty = true; @@ -421,7 +422,10 @@ public abstract class BaseClass> implements List { } /** - * Set the parent of this element and all its descendants. + * Set the parent of this element. + *

+ * Will also check and fix if needed the parent (this) of all its + * descendants (recursively). * * @param parent * the new parent diff --git a/src/be/nikiroo/jvcard/Card.java b/src/be/nikiroo/jvcard/Card.java index 0a405be..6d833d8 100644 --- a/src/be/nikiroo/jvcard/Card.java +++ b/src/be/nikiroo/jvcard/Card.java @@ -15,7 +15,6 @@ import be.nikiroo.jvcard.parsers.Parser; * contacts. * * @author niki - * */ public class Card extends BaseClass { private File file; @@ -97,8 +96,11 @@ public class Card extends BaseClass { 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())) { diff --git a/src/be/nikiroo/jvcard/Contact.java b/src/be/nikiroo/jvcard/Contact.java index 6d362f9..4b4446d 100644 --- a/src/be/nikiroo/jvcard/Contact.java +++ b/src/be/nikiroo/jvcard/Contact.java @@ -15,9 +15,13 @@ import be.nikiroo.utils.StringUtils; /** * A contact is the information that represent a contact person or organisation. + *

+ * 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 { private int nextBKey = 1; @@ -60,7 +64,8 @@ public class Contact extends BaseClass { /** * 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 @@ -77,7 +82,7 @@ public class Contact extends BaseClass { * 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 getData(String name) { @@ -505,8 +510,8 @@ public class Contact extends BaseClass { } /** - * 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 */ @@ -587,12 +592,26 @@ public class Contact extends BaseClass { /** * 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. + *

+ * Will always add one and only one {@link String} (potentially empty) at + * the end of list. * * @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 list) */ static private int addToList(List list, String add, int currentSize, int maxSize) { diff --git a/src/be/nikiroo/jvcard/Data.java b/src/be/nikiroo/jvcard/Data.java index fa9e7c2..0484ade 100644 --- a/src/be/nikiroo/jvcard/Data.java +++ b/src/be/nikiroo/jvcard/Data.java @@ -5,19 +5,21 @@ import java.util.LinkedList; 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. + *

+ * 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 { 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; @@ -169,15 +171,18 @@ public class Data extends BaseClass { /** * Return the bkey number of this {@link Data} or -1 if it is not binary. + *

+ * 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 */ @@ -228,6 +233,9 @@ public class Data extends BaseClass { /** * Return the {@link List} of sep-listed values from this {@link String} * data. + *

+ * Will take the backslash character into account (i.e., a backslash can + * escape the given separator). * * @param value * the data diff --git a/src/be/nikiroo/jvcard/TypeInfo.java b/src/be/nikiroo/jvcard/TypeInfo.java index c172996..4e52a04 100644 --- a/src/be/nikiroo/jvcard/TypeInfo.java +++ b/src/be/nikiroo/jvcard/TypeInfo.java @@ -4,7 +4,6 @@ package be.nikiroo.jvcard; * This class describes a type, that is, a key-value pair. * * @author niki - * */ public class TypeInfo extends BaseClass { private String name; -- 2.27.0