Class CardinalityTransform

  • All Implemented Interfaces:
    JoltTransform, SpecDriven, Transform

    public class CardinalityTransform
    extends java.lang.Object
    implements SpecDriven, Transform
    The CardinalityTransform changes the cardinality of input JSON data elements. The impetus for the CardinalityTransform, was to deal with data sources that are inconsistent with respect to the cardinality of their returned data. For example, say you know that there will be a "photos" element in a document. If your underlying data source is trying to be nice, it may adjust the "type" of the photos element, depending on how many photos there actually are. Single photo :
         "photos" : { "url" : "pants.com/1.jpg" }  // photos element is a "single" map entry
     
    Or multiple photos :
         "photos" : [
            { "url" : "pants.com/1.jpg" },
            { "url" : "pants.com/2.jpg" }
         ]
     
    The Shiftr and Defaultr transforms can't handle that variability, so the CardinalityTransform was created to "fix" document, so that the rest of the transforms can _assume_ "photos" will be an Array. At a base level, a single Cardinality "command" maps data into a "ONE" or "MANY" state. The idea is that you can start with a copy your JSON input and modify it into a Cardinality spec by specifying a "cardinality" for each piece of data that you care about changing in the output. Input data that are not called out in the spec will remain in the output unchanged. For example, given this simple input JSON :
     {
       "review" : {
         "rating" : [ 5, 4 ]
       }
     }
     
    A simple Cardinality spec could be constructed by specifying that the "rating" should be a single value:
     {
       "review" : {
         "rating" : "ONE"
       }
     }
     
    would product the following output JSON :
     {
       "review" : {
         "rating" : 5
       }
     }
     
    In this case, we turn the array "[ 5, 4 ]" into a single value by pulling the first index of the array. Hence, the output has "rating : 5". Valid Cardinality Values (RHS : right hand side) 'ONE' If the input value is a List, grab the first element in that list, and set it as the data for that element For all other input value types, no-op. 'MANY' If the input is not a List, make a list and set the first element to be the input value. If the input is "null", make it be an empty list. If the input is a list, no-op Cardinality Wildcards As shown above, Cardinality specs can be entirely made up of literal string values, but wildcards similar to some of those used by Shiftr can be used. '*' Wildcard Valid only on the LHS ( input JSON keys ) side of a Cardinality Spec Unlike shiftr, the '*' wildcard can only be used by itself. It can be used achieve a for/each manner of processing input. Let's say we have the following input :
     {
       "photosArray" : [
         {
           "url" :  [ "http://pants.com/123-normal.jpg", "http://pants.com/123-thumbnail.jpg" ],
           "caption" : "Nice pants"
         },
         {
           "url" :  [ "http://pants.com/123-thumbnail.jpg", "http://pants.com/123-normal.jpg" ],
           "caption" : "Nice pants"
         }
       ]
     }
     
    And we'd like a spec that says "for each item 'url', covert to ONE" :
     {
       "photosArray" : {
         "*" : { // for each item in the array
           "url" : "ONE"   // url should be singular
         }
       }
     }
     
    Which would yield the following output :
     {
       "photosArray" : [
         {
           "url" :  "http://pants.com/123-normal.jpg",
           "caption" : "Nice pants"
         },
         {
           "url" :  "http://pants.com/123-thumbnail.jpg",
           "caption" : "Nice pants"
         }
       ]
     }
     
    '@' Wildcard Valid only on the LHS of the spec. This wildcard should be used when content nested within modified content needs to be modified as well. Let's say we have the following input:
     {
       "views" : [
         { "count" : 1024 },
         { "count" : 2048 }
       ],
     }
     
    The following spec would convert "views" to a ONE and "count" to a MANY :
     {
       "views" : {
         "@" : "ONE",
         "count" : "MANY"
       }
     }
     
    Yielding the following output:
     {
       "views" : {
         "count" : [ 1024 ]
       }
     }
     
    Cardinality Logic Table
     INPUT   CARDINALITY  OUTPUT   NOTE
     String  ONE          String   no-op
     Number  ONE          Number   no-op
     Boolean ONE          Map      no-op
     Map     ONE          Map      no-op
     List    ONE          [0]      use whatever the first item in the list was
     String  MANY         List     make the input String, be [0] in a new list
     Number  MANY         List     make the input Number, be [0] in a new list
     Boolean MANY         List     make the input Boolean, be [0] in a new list
     Map     MANY         List     make the input Map, be [0] in a new list
     List    MANY         List     no-op
     
    • Constructor Summary

      Constructors 
      Constructor Description
      CardinalityTransform​(java.lang.Object spec)
      Initialize a Cardinality transform with a CardinalityCompositeSpec.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object transform​(java.lang.Object input)
      Applies the Cardinality transform.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • CardinalityTransform

        @Inject
        public CardinalityTransform​(java.lang.Object spec)
        Initialize a Cardinality transform with a CardinalityCompositeSpec.
        Throws:
        SpecException - for a malformed spec
    • Method Detail

      • transform

        public java.lang.Object transform​(java.lang.Object input)
        Applies the Cardinality transform.
        Specified by:
        transform in interface Transform
        Parameters:
        input - the JSON object to transform
        Returns:
        the output object with data shifted to it
        Throws:
        TransformException - for a malformed spec or if there are issues during the transform