com.blackhillsoftware.json.EasySmfGsonBuilder

public final class EasySmfGsonBuilder extends Object

Creates a Gson instance with specialized type adapters for serializing SMF data to JSON using EasySMF.

See: com.google.gson.Gson

Usage

The simplest usage is to use the class to create a Gson instance configured for use with EasySMF, using the default options:

 Gson gson = new EasySmfGsonBuilder().createGson();
 String json = gson.toJson(mySmfRecord);

You can also access the underlying GsonBuilder to specify any Gson options required:

 GsonBuilder gsonBuilder = new EasySmfGsonBuilder().getGsonBuilder();
 gsonBuilder.setPrettyPrinting();
 Gson gson = gsonBuilder.create();
 String json = gson.toJson(mySmfRecord);

Options can be chained in fluent style, so the example above can be re-written as:

 Gson gson = new EasySmfGsonBuilder()
         .getGsonBuilder()    // working with GsonBuilder options from here
         .setPrettyPrinting()
         .create();
 String json = gson.toJson(mySmfRecord);

Customizing the Output

EasySmfGsonBuilder provides several ways to customize the output.

exclude(String) excludes a section or field by name
exclude(Class, String) excludes a section or field of a particular class by name
include(String) always includes a section or field by name. This means that the various exclude options can be overridden on a field by field basis.
include(Class, String) always includes a section or field of a particular class by name This means that the various exclude options can be overridden on a field by field basis.
includeZeroValues(boolean) indicates whether fields with zero values should be included. Default: true. When false, this can be overridden for individual fields using include(String)
includeEmptyStrings(boolean) indicates whether fields with empty string values should be included. Default: true. When false, this can be overridden for individual fields using include(String)
alias(Class, String, String) use a different name for a field of a class
addEntry(Class, String, Object) allows you to add a fixed value to each entry generated for a particular class
calculateEntry(Class, String, Function) allows you to provide a function or lambda to add a calculated value to each entry for a class.
EasySMF provides the data from some fields in multiple formats. For example, CPU time is usually available as a java.time.Duration, a value converted to seconds, and the unconverted RawValue. The following options allow you to select which of these values should be included across all records and sections. By default, the values in seconds are included in the generated JSON.
- includeRawValues(boolean) - default: false
- durationAsDuration(boolean) - default: false
- durationAsSeconds(boolean) - default: true

CICS Specific Options

CICS transactions are different to other SMF data because the available fields are defined by a dictionary. CICS transaction information also produces a large quantity of output. For these reasons there are several options specific to CICS transaction information:

cicsExcludeGroup(String) Exclude a group of transactions by owner e.g. "DFHWEBB"

cicsVerbose(boolean) - default: false

Verbose format includes all the field identification information in the JSON output eg:

 "values": [
 {
    "cmodHead": "START",
    "cmodName": "DFHCICS",
    "ident": "T005",
    "value": "2019-10-29T14:02:54.383214723Z"
  },
  {
    "cmodHead": "STOP",
    "cmodName": "DFHCICS",
    "ident": "T006",
    "value": "2019-10-29T14:02:54.383481508Z"
  },
  ...

Non-verbose format only includes field names:

  "start": "2019-10-29T14:02:54.383214723Z",
  "stop": "2019-10-29T14:02:54.383481508Z",
  ...

cicsClockDetail(boolean) - default: true
Indicates whether CICS clock fields are complex values including the timer value, count and flags fields. To reduce the amount of output set this to false and only the timer value in seconds will be provided.

Type Adapters

EasySmfGsonBuilder sets up TypeAdapters for the following data types used in EasySMF:

EasySMF records and sections
java.time Classes:
- Duration
- Instant
- LocalDate
- LocalDateTime
- LocalTime
- OffsetDateTime
- OffsetTime
- Period
- ZonedDateTime
- ZoneId
- ZoneOffset
byte[] byte array

It also provides the option to modify the formatting for floating point values to avoid the use of scientific notation which makes the JSON more (human) readable.

Constructor Summary

Constructors

Constructor

Description

EasySmfGsonBuilder()

Create an EasySmfGsonBuilder instance
Method Summary

Modifier and Type

Method

Description

EasySmfGsonBuilder

addEntry(Class<? extends SmfData> targetType, String name, Object value)

Add a fixed value to the generated JSON for every record or section of a particular type

EasySmfGsonBuilder

alias(Class<? extends SmfData> targetType, String fromName, String toName)

Rename a section or field from a specific record or section type.

EasySmfGsonBuilder

avoidScientificNotation(boolean value)

Use decimal numbers instead of scientific notation for a wider range of double and float values (true/false).

<T extends SmfData> EasySmfGsonBuilder

calculateEntry(Class<T> targetType, String name, Function<T,Object> value)

Add a calculated value to the JSON for every record or section of a particular type

EasySmfGsonBuilder

cicsClockDetail(boolean value)

Include detailed data for CICS clocks (true/false).

EasySmfGsonBuilder

cicsExcludeGroup(String name)

Exclude a group of fields from CICS transaction data

EasySmfGsonBuilder

cicsVerbose(boolean value)

Export CICS transaction data in verbose format (true/false).

Gson

createGson()

Create the Gson instance configured to serialize SMF data from EasySMF records and sections into JSON.

EasySmfGsonBuilder

decimalPlaces(int value)

Set the maximum number of decimal places to be used in double and floating point numbers (1-9).

EasySmfGsonBuilder

durationAsDuration(boolean value)

Indicate whether Duration entries for time values (CPU time etc) should be included.

EasySmfGsonBuilder

durationAsSeconds(boolean value)

Indicate whether time values (CPU time etc) converted to seconds should be included.

EasySmfGsonBuilder

exclude(MonitoringField field)

Exclude a CICS monitoring field.

EasySmfGsonBuilder

exclude(Class<? extends SmfData> targetType, String name)

Exclude a section or field from a specific record or section type by name.

EasySmfGsonBuilder

exclude(String name)

Exclude a section or field by name.

GsonBuilder

getGsonBuilder()

Get the underlying GsonBuilder for this class, allowing additional GsonBuilder options to be specified.

EasySmfGsonBuilder

include(MonitoringField field)

Include a CICS monitoring field.

EasySmfGsonBuilder

include(Class<? extends SmfData> targetType, String name)

Include a section or field from a specific record or section type by name.

EasySmfGsonBuilder

include(String name)

Include a section or field by name.

EasySmfGsonBuilder

includeDeprecated(boolean value)

Indicate whether fields that are marked as Deprecated in the EasySMF API should be included

EasySmfGsonBuilder

includeEmptyStrings(boolean value)

Include fields with empty strings in the output (true/false).

EasySmfGsonBuilder

includeRawValues(boolean value)

Indicate whether the ...RawValue() entries should be included in the output where they are provided, eg java.time entries where the value is converted to Duration, LocalDateTime, Seconds etc.

EasySmfGsonBuilder

includeSectionType(boolean value)

Indicate whether a "sectionType" entry should be added to each section with name of the section class.

EasySmfGsonBuilder

includeUnsetFlags(boolean value)

Indicate whether flags returned as boolean values should be included if the flag is not set (i.e. the value is zero/false)

EasySmfGsonBuilder

includeZeroValues(boolean value)

Include fields with zero values in the output (true/false).

EasySmfGsonBuilder

setPrettyPrinting()

Call setPrettyPrinting() on the underlying GsonBuilder

EasySmfGsonBuilder

timesAsEpochSeconds(boolean value)

Indicate whether time values (ZonedDateTime, OffsetDateTime, Instant) should be expressed as seconds from the Unix epoch

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- EasySmfGsonBuilder
  
  public EasySmfGsonBuilder()
  
  Create an EasySmfGsonBuilder instance
Method Details
- getGsonBuilder
  
  public GsonBuilder getGsonBuilder()
  
  Get the underlying GsonBuilder for this class, allowing additional GsonBuilder options to be specified.
  
  Returns:
  
  GsonBuilder
- createGson
  
  public Gson createGson()
  
  Create the Gson instance configured to serialize SMF data from EasySMF records and sections into JSON.
  
  Returns:
  
  the Gson instance
- includeRawValues
  
  public EasySmfGsonBuilder includeRawValues(boolean value)
  
  Indicate whether the ...RawValue() entries should be included in the output where they are provided, eg java.time entries where the value is converted to Duration, LocalDateTime, Seconds etc.
  Default: false
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- includeSectionType
  
  public EasySmfGsonBuilder includeSectionType(boolean value)
  
  Indicate whether a "sectionType" entry should be added to each section with name of the section class. Useful when the field name doesn't specifically indicate the type e.g. CICS statistics sections where the sections are specialized types of a base class.
  Default: false
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- durationAsDuration
  
  public EasySmfGsonBuilder durationAsDuration(boolean value)
  
  Indicate whether Duration entries for time values (CPU time etc) should be included. See also durationAsSeconds(boolean)
  Default: false
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- durationAsSeconds
  
  public EasySmfGsonBuilder durationAsSeconds(boolean value)
  
  Indicate whether time values (CPU time etc) converted to seconds should be included. See also durationAsDuration(boolean)
  Default: true
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- timesAsEpochSeconds
  
  public EasySmfGsonBuilder timesAsEpochSeconds(boolean value)
  
  Indicate whether time values (ZonedDateTime, OffsetDateTime, Instant) should be expressed as seconds from the Unix epoch
  Default: false
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- includeUnsetFlags
  
  public EasySmfGsonBuilder includeUnsetFlags(boolean value)
  
  Indicate whether flags returned as boolean values should be included if the flag is not set (i.e. the value is zero/false)
  Default: true - values are always included
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- includeDeprecated
  
  public EasySmfGsonBuilder includeDeprecated(boolean value)
  
  Indicate whether fields that are marked as Deprecated in the EasySMF API should be included
  Default: false
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- setPrettyPrinting
  
  public EasySmfGsonBuilder setPrettyPrinting()
  
  Call setPrettyPrinting() on the underlying GsonBuilder
  
  Returns:
  
  this EasySmfGsonBuilder
- cicsVerbose
  
  public EasySmfGsonBuilder cicsVerbose(boolean value)
  
  Export CICS transaction data in verbose format (true/false).
  Verbose format includes the owner name (e.g. DFHCICS), field identifier (e.g. T005) and informal name (e.g. START). Otherwise only the informal name is included, or the informal name combined with the identifier if the informal name is not unique (e.g. SCUSRHWM_A033).
  
  Parameters:
  
  value - true/false, default false.
  
  Returns:
  
  this EasySmfGsonBuilder
- includeZeroValues
  
  public EasySmfGsonBuilder includeZeroValues(boolean value)
  
  Include fields with zero values in the output (true/false).
  SMF data typically includes many fields with zero values. To reduce the amount of JSON generated, set includeZeroValues(false) to omit zero values from the generated JSON.
  
  Parameters:
  
  value - true/false, default true.
  
  Returns:
  
  this EasySmfGsonBuilder
- includeEmptyStrings
  
  public EasySmfGsonBuilder includeEmptyStrings(boolean value)
  
  Include fields with empty strings in the output (true/false).
  SMF data can include many fields with empty string values. To reduce the amount of JSON generated, set includeEmptyStrings(false) to omit empty string values from the generated JSON.
  
  Parameters:
  
  value - true/false, default true.
  
  Returns:
  
  this EasySmfGsonBuilder
- cicsClockDetail
  
  public EasySmfGsonBuilder cicsClockDetail(boolean value)
  Include detailed data for CICS clocks (true/false).
  CICS clock values include a timer value, a count field and flags. To reduce the amount of JSON generated, you can set cicsClockDetail to false and only the timer value will be included in the output.
  e.g.
  
  cicsClockDetail(true):
  "usrcput":{"timerSeconds":0.000274924,"count":1,"flags":"0x00"}
  
  cicsClockDetail(false):
  "usrcputSeconds":0.000274924
  
  Note: You can only addEntry(Class, String, Object) or calculateEntry(Class, String, Function) values for CICS clocks if cicsClockDetail is true.
  Parameters:
  
  value - true/false, default true.
  
  Returns:
  
  this EasySmfGsonBuilder
- cicsExcludeGroup
  
  public EasySmfGsonBuilder cicsExcludeGroup(String name)
  
  Exclude a group of fields from CICS transaction data
  
  Parameters:
  
  name - The owner name of the group e.g. "DFHWEBB"
  
  Returns:
  
  this EasySmfGsonBuilder
- exclude
  
  public EasySmfGsonBuilder exclude(String name)
  
  Exclude a section or field by name. The name is the name of the section or field in the parent section, e.g. smf30cpt or excpSections
  
  Parameters:
  
  name - The name of the section or field
  
  Returns:
  
  this EasySmfGsonBuilder
- exclude
  
  public EasySmfGsonBuilder exclude(Class<? extends SmfData> targetType, String name)
  
  Exclude a section or field from a specific record or section type by name.
  
  Parameters:
  
  targetType - The class for the exclusion, e.g. ProcessorAccountingSection.class or Smf30Record.class
  
  name - The name of the section or field e.g. smf30cpt or excpSections
  
  Returns:
  
  this EasySmfGsonBuilder
- exclude
  
  public EasySmfGsonBuilder exclude(MonitoringField field)
  
  Exclude a CICS monitoring field.
  
  Parameters:
  
  field - the CICS MonitoringField
  
  Returns:
  
  this EasySmfGsonBuilder
- include
  
  public EasySmfGsonBuilder include(String name)
  
  Include a section or field by name. The name is the name of the section or field in the parent section, e.g. smf30cpt or excpSections. Include overrides any exclude options e.g. cicsExcludeGroup(String) includeZeroValues(boolean), durationAsDuration(boolean)
  
  Parameters:
  
  name - The name of the section or field
  
  Returns:
  
  this EasySmfGsonBuilder
- include
  
  public EasySmfGsonBuilder include(MonitoringField field)
  
  Include a CICS monitoring field.
  
  Parameters:
  
  field - the CICS MonitoringField
  
  Returns:
  
  this EasySmfGsonBuilder
- include
  
  public EasySmfGsonBuilder include(Class<? extends SmfData> targetType, String name)
  
  Include a section or field from a specific record or section type by name. Include overrides any exclude options e.g. cicsExcludeGroup(String) includeZeroValues(boolean), durationAsDuration(boolean)
  
  Parameters:
  
  targetType - The class for the exclusion, e.g. ProcessorAccountingSection.class or Smf30Record.class
  
  name - The name of the section or field e.g. smf30cpt or excpSections
  
  Returns:
  
  this EasySmfGsonBuilder
- alias
  
  public EasySmfGsonBuilder alias(Class<? extends SmfData> targetType, String fromName, String toName)
  
  Rename a section or field from a specific record or section type.
  
  Parameters:
  
  targetType - The class for the alias, e.g. ProcessorAccountingSection.class or Smf30Record.class
  
  fromName - The name of the section or field e.g. smf30cpt or excpSections
  
  toName - The desired name of the section or field
  
  Returns:
  
  this EasySmfGsonBuilder
- avoidScientificNotation
  
  public EasySmfGsonBuilder avoidScientificNotation(boolean value)
  
  Use decimal numbers instead of scientific notation for a wider range of double and float values (true/false). This makes values easier to read by a human, particularly when looking at small numbers e.g. transaction CPU times.
  Default: false - Gson default scientific notation will be used
  
  Parameters:
  
  value - true or false
  
  Returns:
  
  this EasySmfGsonBuilder
- decimalPlaces
  
  public EasySmfGsonBuilder decimalPlaces(int value)
  
  Set the maximum number of decimal places to be used in double and floating point numbers (1-9). Implies avoidScientificNotation(true).
  Default: no maximum - default formatting will be used.
  
  Parameters:
  
  value - maximum number of decimal places, from 1 to 9.
  
  Returns:
  
  this EasySmfGsonBuilder
- addEntry
  
  public EasySmfGsonBuilder addEntry(Class<? extends SmfData> targetType, String name, Object value)
  Add a fixed value to the generated JSON for every record or section of a particular type
  Gson gson = new EasySmfGsonBuilder() .addEntry(Smf7Record.class, "event", "SMF Data Lost") .createGson();
  Parameters:
  
  targetType - The class to to add data to, e.g. Smf7Record.class
  
  name - The JSON entry name e.g. "event"
  
  value - The JSON entry value e.g. "SMF data lost"
  
  Returns:
  
  this EasySmfGsonBuilder
- calculateEntry
  
  public <T extends SmfData> EasySmfGsonBuilder calculateEntry(Class<T> targetType, String name, Function<T,Object> value)
  Add a calculated value to the JSON for every record or section of a particular type
  Gson gson = new EasySmfGsonBuilder() .calculateEntry(Smf30Record.class, "elapsed", r30 -> { return Duration.between( r30.identificationSection().smf30std() .atTime(r30.identificationSection().smf30sit()), r30.smfDate());} ) .createGson();
  Type Parameters:
  
  T - Represents the type of the object input to the calculation function (the same class as the targetType parameter)
  
  Parameters:
  
  targetType - The class to to add data to, e.g. Smf30Record.class
  
  name - The JSON entry name e.g. "day_of_week"
  
  value - The calculation to produce the value e.g. r30 -> { return r30.smfDate().getDayOfWeek();}
  
  Returns:
  
  this EasySmfGsonBuilder

Class EasySmfGsonBuilder

Usage

Customizing the Output

CICS Specific Options

Type Adapters

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

EasySmfGsonBuilder

Method Details

getGsonBuilder

createGson

includeRawValues

includeSectionType

durationAsDuration

durationAsSeconds

timesAsEpochSeconds

includeUnsetFlags

includeDeprecated

setPrettyPrinting

cicsVerbose

includeZeroValues

includeEmptyStrings

cicsClockDetail

cicsExcludeGroup

exclude

exclude

exclude

include

include

include

alias

avoidScientificNotation

decimalPlaces

addEntry

calculateEntry