org.openntf.jsonbeanx
Class J2BSettings

java.lang.Object
  org.openntf.jsonbeanx.J2BSettings

public class J2BSettings
extends java.lang.Object

Settings used by J2BConverter when you are converting between JSON strings and Java beans. See the comments of the various methods for a description of what they do.

Since:

0.9.2

Author:

Julian Robichaux

Constructor Summary

J2BSettings()

Method Summary

void	addFieldMapping(java.lang.String jsonFieldName, java.lang.String setterMethodName) Add a mapping of JSON fieldname to a setter method in a Java bean; this is used for converting a JSON string to a Java bean.
void	addJSONClassPrefix(java.lang.Class clazz, java.lang.String fieldName) Use this if you want the Map of values for a Java bean class to be prefixed with a field name, or if you are processing JSON that prefixes a Map of values for a particular object with a field name.
void	addMethodMapping(java.lang.String getterMethodName, java.lang.String jsonFieldName) Add a mapping of a getter method in a Java bean to a JSON field name; this is used for converting a Java bean to a JSON string.
void	addRequiredField(java.lang.Class clazz, java.lang.String fieldName) Add a JSON field name that is required when a specific class is being used to generate a Java bean from JSON.
void	addUnloggableField(java.lang.String fieldName) Add a field to the "unloggable list" in settings, which means that the value of this JSON field will never be written to the logs or returned in an Exception message.
java.lang.String	getDateFormat() Returns the date format string used for converting between Date objects and Strings (and back)
java.util.Map<java.lang.String,java.lang.String>	getFieldMap() Returns the JSON fieldname to setter method name mappings currently being used.
java.lang.String	getJSONClassPrefix(java.lang.Class clazz) Returns the JSON fieldName that a Java bean class should be prefixed with (as set in addJSONClassPrefix(Class, String)), or null if there should be no prefix for this class.
java.util.logging.Logger	getLogger() Returns the logger being used by these settings, if any.
java.util.Map<java.lang.String,java.lang.String>	getMethodMap() Returns the getter method to JSON fieldname mappings currently being used.
java.util.List<java.lang.String>	getMissingFields(java.lang.Object parent, java.util.Map values) Return a List of any fields missing in the given Map that will be used to create the given object, based on fields added using addRequiredField(Class, String).
java.util.Set<java.lang.String>	getRequiredFields(java.lang.Class clazz) Return a Set of all fields required for a specific class, added using addRequiredField(Class, String)
boolean	isFieldLoggable(java.lang.String fieldName) Returns true if a field value can be logged (based on fields set by addUnloggableField(String)), false otherwise.
boolean	isLoggable(java.util.logging.Level level) Returns the result of Logger.isLoggable() if there is a logger attached to this settings object; otherwise returns false.
boolean	isMappingFailureFatal() Returns the value set by setMappingFailureFatal(boolean) (default is false).
void	log(java.util.logging.Level level, java.lang.String message, java.lang.Throwable t) Log the given message at the given Level to the Logger (if any).
void	removeRequiredField(java.lang.Class clazz, java.lang.String fieldName) Remove a required field that was added by addRequiredField(Class, String)
void	removeUnloggableField(java.lang.String fieldName) Remove a field from the "unloggable list".
void	setAllowMappedDuplicates(boolean allowMappedDuplicates) Set this to true if you want to use fields and methods that are would otherwise be overridden by field and method mappings.
void	setDateFormat(java.lang.String dateFormat) Set the date format string used for converting between Date objects and Strings (and back).
void	setLogger(java.util.logging.Logger logger) Use the given Logger to log all internal messages (at Level.FINE) and exceptions (at Level.WARNING) produced when the J2BConverter runs.
void	setMappingFailureFatal(boolean isFatal) Set this to be true if you want the J2BConverter to throw an Exception if it cannot find a setter method that corresponds to any of the JSON fields that it processes.
void	setSkipNullValues(boolean skipNullValues) Set this to true if you want null values to be skipped when creating a JSON string from beans, or when creating a bean from JSON (default is false).
boolean	shouldAllowMappedDuplicates() Returns the value set by setAllowMappedDuplicates(boolean) (default is false)
boolean	shouldSkipNullValues() Returns the value set by setSkipNullValues(boolean) (default is false).

Methods inherited from class java.lang.Object

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

Constructor Detail

J2BSettings

public J2BSettings()

Method Detail

setLogger

public void setLogger(java.util.logging.Logger logger)

Use the given Logger to log all internal messages (at Level.FINE) and exceptions (at Level.WARNING) produced when the J2BConverter runs. There is also verbose logging available at Level.FINEST.

The most important reason to use a logger is to see the chain of events that causes an Exception. If any of the J2BConverter methods fail with an error, they return an error message giving the exact problem and corresponding stack trace. However, sometimes it is hard to determine at exactly what point the error happened without additional information. Setting a logger here will send additional information about where an error happened to the log at Level.WARNING.

At Level.FINE you see information about fields that are skipped and non-fatal potential issues, and at Level.FINEST you see information about exactly how each field is mapped to a method. If you are logging at Level.FINE or FINEST, make sure that your log handler will accept messages at those levels. For example, if you are logging to the console, a lot of time the console will only display messages at Level.WARNING or SEVERE. The trace log is usually a good place to look.

getLogger

public java.util.logging.Logger getLogger()

Returns the logger being used by these settings, if any.

log

public void log(java.util.logging.Level level,
                java.lang.String message,
                java.lang.Throwable t)

Log the given message at the given Level to the Logger (if any). This method is intended for use by the J2BConverter code when it runs, but you can use it too if you want.

isLoggable

public boolean isLoggable(java.util.logging.Level level)

Returns the result of Logger.isLoggable() if there is a logger attached to this settings object; otherwise returns false.

addFieldMapping

public void addFieldMapping(java.lang.String jsonFieldName,
                            java.lang.String setterMethodName)

Add a mapping of JSON fieldname to a setter method in a Java bean; this is used for converting a JSON string to a Java bean. For example, if the JSON field is called "cost" and you want to use the "setTotalCost" method in a bean when this field is processed, add a field mapping for "cost" and "setTotalCost" using this method. Otherwise the converter will attempt to use a "setCost" method to set the "cost" field. Note that your setter method must have exactly one parameter.

If multiple fields are mapped to the same method, that method will be run for each field mapped to that method, which may result in the method being run more than once (and bean data getting overwritten).

getFieldMap

public java.util.Map<java.lang.String,java.lang.String> getFieldMap()

Returns the JSON fieldname to setter method name mappings currently being used. This is used for converting a JSON string to a Java bean.

addMethodMapping

public void addMethodMapping(java.lang.String getterMethodName,
                             java.lang.String jsonFieldName)

Add a mapping of a getter method in a Java bean to a JSON field name; this is used for converting a Java bean to a JSON string. For example, if the JSON field is called "cost" and you want to use the "getTotalCost" method in a bean to populate this field, add a method mapping for "getTotalCost" and "cost" using this method. Otherwise the converter will attempt to set a JSON "totalCost" field for the a "getTotalCost" method.

You can also use this to specify the JSON field name of a class. If you want to specify that a specific method is NOT mapped to JSON, use null as the fieldName value.

If multiple methods are mapped to the same field name, a JSON field will be produced for each method mapped to that field, which may result in duplicate fields.

getMethodMap

public java.util.Map<java.lang.String,java.lang.String> getMethodMap()

Returns the getter method to JSON fieldname mappings currently being used. This is used for converting a Java bean to a JSON string.

setMappingFailureFatal

public void setMappingFailureFatal(boolean isFatal)

Set this to be true if you want the J2BConverter to throw an Exception if it cannot find a setter method that corresponds to any of the JSON fields that it processes. The default value is false, which means that JSON fields with no mappings are logged (if a Logger has been set via setLogger(Logger)) and skipped.

isMappingFailureFatal

public boolean isMappingFailureFatal()

Returns the value set by setMappingFailureFatal(boolean) (default is false).

shouldSkipNullValues

public boolean shouldSkipNullValues()

Returns the value set by setSkipNullValues(boolean) (default is false).

setSkipNullValues

public void setSkipNullValues(boolean skipNullValues)

Set this to true if you want null values to be skipped when creating a JSON string from beans, or when creating a bean from JSON (default is false). If this is false and you are converting JSON to beans, the appropriate bean setter method will be called with null as a parameter. If this is false and you are creating JSON from a bean, and a getter method returns null, the corresponding JSON field value will be written with a null value.

Interesting note: if you are building a bean from JSON and there is a primitive parameter with a null JSON value, it will work -- the default value of the primitive will be assigned (not sure how, maybe because of autoboxing?).

getDateFormat

public java.lang.String getDateFormat()

Returns the date format string used for converting between Date objects and Strings (and back)

setDateFormat

public void setDateFormat(java.lang.String dateFormat)

Set the date format string used for converting between Date objects and Strings (and back). See SimpleDateFormat for format String options.

NOTE: the default date format does not include seconds, so if you compare dates that have been exported and imported back in, they will not be the same. If you are dealing with Date values you almost always want a custom format string.

addJSONClassPrefix

public void addJSONClassPrefix(java.lang.Class clazz,
                               java.lang.String fieldName)

Use this if you want the Map of values for a Java bean class to be prefixed with a field name, or if you are processing JSON that prefixes a Map of values for a particular object with a field name. For example, if your class is:

 public class MyBean {
     private String field1;
     // getters and setters below...
 }
 

the default JSON that would be produced would be like:

{"field1": "value"}

setting addJSONClassPrefix(MyBean.class, "mbean"); would result in JSON like:

{"mbean": {"field1": "value"}}

Likewise, if the JSON you are converting to a bean uses the {"mbean": {"field1": "value"}} format, you need to set use this method to create a proper mapping.

getJSONClassPrefix

public java.lang.String getJSONClassPrefix(java.lang.Class clazz)

Returns the JSON fieldName that a Java bean class should be prefixed with (as set in addJSONClassPrefix(Class, String)), or null if there should be no prefix for this class.

shouldAllowMappedDuplicates

public boolean shouldAllowMappedDuplicates()

Returns the value set by setAllowMappedDuplicates(boolean) (default is false)

setAllowMappedDuplicates

public void setAllowMappedDuplicates(boolean allowMappedDuplicates)

Set this to true if you want to use fields and methods that are would otherwise be overridden by field and method mappings.

For example, let's say you mapped the "cost" field to the "setTotalCost" method in a bean. If the JSON also has a "totalCost" field then the default operation of J2BConverter is to ignore the "totalCost" field (unless some other method was mapped to it) so that the "setTotalCost" method is only used for processing "cost". Setting allowMappedDuplicates=true means that "setTotalCost" would be called when both the "cost" and the "totalCost" fields are encountered, which could result in duplication.

The same is true for method mappings, used for generating JSON. If you map the method "getTotalCost" to the "cost" field, and you also have a "getCost" method, the default behavior is to ignore the "getCost" method unless it is mapped to another JSON field. allowMappedDuplicates=true allows both the "getTotalCost" and "getCost" methods of a bean to generate a JSON field called "cost", which could result in duplication.

addUnloggableField

public void addUnloggableField(java.lang.String fieldName)

Add a field to the "unloggable list" in settings, which means that the value of this JSON field will never be written to the logs or returned in an Exception message. If you are receiving or sending sensitive information with JSON (like passwords, account numbers, etc.) you might want to make sure that this information is never written to a log.

removeUnloggableField

public void removeUnloggableField(java.lang.String fieldName)

Remove a field from the "unloggable list".

See Also:

addUnloggableField(String)

isFieldLoggable

public boolean isFieldLoggable(java.lang.String fieldName)

Returns true if a field value can be logged (based on fields set by addUnloggableField(String)), false otherwise.

addRequiredField

public void addRequiredField(java.lang.Class clazz,
                             java.lang.String fieldName)

Add a JSON field name that is required when a specific class is being used to generate a Java bean from JSON. Multiple fields for a given class can be added with multiple calls to this method. If a required JSON field is not available when J2BConverter.jsonToBean(Class, String, J2BSettings) is creating the class object from JSON, the process will fail with an Exception.

For example, if you call jsonToBean(MoneyTransfer.class, json, settings) and you want the converter to fail if there is no "accountNumber" field in the JSON, simply call settings.addRequiredField(MoneyTransfer.class, "accountNumber") before calling jsonToBean.

You can also require fields for classes that are fields inside the top-level bean that is created by jsonToBean.

Note that you must specify the exact class that is created in the jsonToBean process. If you specify an interface or a superclass it will not work.

removeRequiredField

public void removeRequiredField(java.lang.Class clazz,
                                java.lang.String fieldName)

Remove a required field that was added by addRequiredField(Class, String)

getRequiredFields

public java.util.Set<java.lang.String> getRequiredFields(java.lang.Class clazz)

Return a Set of all fields required for a specific class, added using addRequiredField(Class, String)

getMissingFields

public java.util.List<java.lang.String> getMissingFields(java.lang.Object parent,
                                                         java.util.Map values)

Return a List of any fields missing in the given Map that will be used to create the given object, based on fields added using addRequiredField(Class, String). This is called by J2BConverter methods.