USER MANUALS

JSON Wrappers

This section explains the syntax used to create JSON wrappers over JSON data sources.

Syntax of the CREATE WRAPPER JSON statement
CREATE [ OR REPLACE ] WRAPPER JSON <name:identifier>
    [ FOLDER = <literal> ]
    DATASOURCENAME = <name:identifier>
    [ TUPLEROOT <JSON path:literal> ]
    [ ROUTE <route> [ CHARSET = <literal> ] [ <route filters> ] ]
    [ OUTPUTSCHEMA ( <field> [, <field> ]* ) ]
    [ SOURCECONFIGURATION ( [ <source configuration property>
                            [, <source configuration property> ]* ] ) ]

<route> ::=
    HTTP <connection class name:literal> { GET | POST } <uri:literal>
    [ POSTBODY <body:literal> [ MIME <mimetype:literal> ] ]
    [ HEADERS (
         <header name:literal> = <header value:literal>
         [, <header name:literal> = <header value:literal> ]*
             )
    ]
    [ PAGINATION_SETTINGS ( <pagination settings> ) ]
    [ CHARSET = <encoding:literal> ]

<pagination settings> ::=
    PAGE_SIZE_PARAMETER = <literal>
    PAGE_SIZE = <integer>
    PAGE_NUMBER_PARAMETER = <literal>
    FIRST_PAGE_INDEX = <integer>
    OFFSET_FOR_NEXT_REQUESTS = <integer>
    MAX_NUMBER_OF_REQUESTS = <integer>
   |
    PAGE_SIZE_PARAMETER = <literal>
    PAGE_SIZE = <integer>
    NEXT_TOKEN_PARAMETER = <literal>
    NEXT_TOKEN_PATH = <literal>
    [ MAX_NUMBER_OF_REQUESTS = <integer> ]
   |
    PAGE_SIZE_PARAMETER = <literal>
    PAGE_SIZE = <integer>
    NEXT_TOKEN_PATH = <literal>
    [ MAX_NUMBER_OF_REQUESTS = <integer> ]
   |
    HEADER_WITH_NEXT_PAGE_URL = <literal>
    [ MAX_NUMBER_OF_REQUESTS = <integer> ]

<route filters> ::=
    FILTER ( <route filter> [, <route filter> ]* )

<route filter> ::= {
    DECRYPTAES256 PASSWORD = <literal> [ ENCRYPTED ]
  | DECRYPT PASSWORD = <literal> [ ENCRYPTED ]
  | UNZIP
  | GUNZIP
  | CUSTOM [ JARS <jar name:literal> [, <jar name:literal> ]* ]
    CLASSNAME = <literal> [ <route filter parameter> ]*
}

<route filter parameter> ::=
     <parameter name:identifier> = <literal> [ ENCRYPTED ] [ HIDDEN ]

<field> ::=
      <name:identifier> [ = <mapping:literal> ] [ : <type:literal>]
        [ ( { OBL | OPT } ) ]
        [ ( DEFAULTVALUE <literal> ) ]
        [ EXTERN ]
        [ <inline constraints> ]*
    | <name:identifier> [ = <mapping:literal> ] :
        ARRAY OF ( <register field> )
        [ ( DEFAULTVALUE <literal> ) ]
        [ <inline constraints> ]*
    | <name:register field>

<register field> ::=
    <name:identifier> [ = <mapping:literal> ] :
        REGISTER OF ( <field> [, <field> ]* )
          [ ( DEFAULTVALUE <literal> ) ]
          [ <inline constraints> ]*

<inline constraint> ::=
      [ NOT ] NULL
    | [ NOT ] UPDATEABLE
    | { SORTABLE [ ASC | DESC ] | NOT SORTABLE }
    | URIPARAM

<source configuration property> ::=
    DATAINORDERFIELDSLIST = { DEFAULT | ( <name:identifier> { ASC | DESC }
                                      [, <name:identifier> { ASC | DESC } ]* ) }

The syntax of the modification statement of a JSON wrapper is similar.

Syntax of the ALTER WRAPPER JSON statement
ALTER WRAPPER JSON <name:identifier>
    [ DATASOURCENAME = <name:identifier> ]
    [ TUPLEROOT <JSON path:literal> ]
    [ ROUTE <route> [ CHARSET = <literal> ] [ <route filters> ] ]
    [ OUTPUTSCHEMA ( <field> [, <field> ]* ) ]
    [ SOURCECONFIGURATION ( [ <source configuration property>
    [, <source configuration property> ]* ] ) ]

Virtual DataPort supports the creation of wrappers on documents in JSON format. To create a wrapper of this type the name of the data source must be indicated (DATASOURCENAME parameter).

JSON wrappers can have an associated HTTP route, which must be declared using the ROUTE parameter. When a request is executed, the URL of this route is concatenated to the URL of the data source route. This way, a data source that defines a base URL (for example: http://www.library.com/) can be reused to create a wrapper with its own relative URL for each resource we want to access (for example: “/books”, “/authors”, “/bookById/{id}”, etc).

The JSON wrapper analyzes the structure of the document and returns the JSON tags of the first level as attributes (using their name as the attribute name), encapsulating the other elements in compound types. As with the other wrappers, the schema returned by the wrapper may be specified (OUTPUTSCHEMA).

The wrapper creation statement also accepts the OR REPLACE modifier. Where specified, if there is already a wrapper with the same name, its definition is replaced by the new one.

The clause URIPARAM is always used along with the clause EXTERN, which indicates that this field represents the value of an interpolation variable. By adding URIPARAM, the value of the field will be encoded as a query parameter of a URL. URIPARAM should only be added when the wrapper is created over JSON data sources whose path is HTTP and the variable is the value of a URL’s query parameter. See more details about this in the section HTTP Path (subsection of Path Types in Virtual DataPort) of the Administration Guide.

Lastly, certain wrapper properties can be specified (SOURCECONFIGURATION). Virtual DataPort will take them into account to determine the operations that can be made on the wrapper. The applicable properties are indicated in the corresponding statement declaration (Syntax of the CREATE WRAPPER JSON statement), and are explained in the section Wrapper Configuration Properties.

Add feedback