LDDL

LAPPS Database Definition Language

LDDL is a Groovy DSL (Domain Specific Language) that can be used to initialize a PostgreSQL database for use with the LAPPS service grid.  In particular, metadata, service types, resource types, and services can all be configured via LDDL scripts, greatly simplifying unit and integration testing.  LDDL scripts are also a good way to ensure that multiple nodes on the LAPPS grid use the same metadata, types, and service definitions.

Because LDDL is a Groovy DSL, it has the expressive power of any Groovy program, including flow of control (loops, iterators, conditionals) and data structures (lists,  maps, sets, etc.), plus the ability to import (including using @Grab) other Groovy and Java classes in a LDDL script. If you are unfamiliar with Groovy, you may want to read a short introduction to Groovy.

LDDL scripts consist of one or more keywords followed by a closure (a block inside curly braces) with initialization information. The initialization information consists of a sequence (one per line) of names followed by a value.

keyword {
    name 'a value'
    anotherName 'another value'
    ...
}

Note that the assignment operator (‘=’) is not required between the name and the value. In fact it is an error to use the assignment operator.

Installation

The LDDL jar file can be downloaded here. LDDL is released under the Apache 2.0 license. The LDDL scripts required to setup and configure a LAPPS node are also available here.  Note: the Services.lddl script will need to be edited to add your local services as opposed to the services running on the ANC’s node.

The LDDL source code can be obtained from github.

Usage

java -jar LDDL-x.y.z.jar configScript.lddl

Statements

  1. database
  2. postgres
  3. domain
  4. protocol
  5. resourceMetaAttribute
  6. resourceType
  7. resource
  8. serviceMetaAttribute
  9. serviceType
  10. service
  11. serviceInterfaceDefinition
  12. news
  13. sql
  14. include

database

The database section is used to specify the information needed to connect to the PostgreSQL database. The following values are required:

Name Description
url The JDBC URL used to connect to the database
username The name of the database user.
password The password of the database user.

example

database {
    url 'jdbc:postgres://localhost/databasename'
    username 'langrid'
    password 'langrid'
}

Note In addition to establishing a connection to the database the values of the gridid, nodeid and owneruserid are retrieved from the node table and stored in the LDDL global variables GRID_ID, NODE_ID, and GRID_USER_ID respectively.

postgres

The postgres section functions identically to the database section except the node table is not queried and the GRID_ID, NODE_ID, and GRID_USER_ID variables are not initialized. This is useful when a connection to a different database is required or when the service grid database needs to be dropped.

Name Description
url The JDBC URL used to connect to the database
username The name of the database user.
password The password of the database user.

example

postgres {
    url 'jdbc:postgres://localhost'
    username 'postgres'
    password 'postgres'
}
sql 'drop database if exists langrid'

domain

The domain keyword is used to declare a service grid domain.

Name Description
id the domain ID.
name a human readable name for the domain
description a description of the domain

example

domain {
    id 'lapps.nlp'
    name 'LAPPS NLP'
    description 'Anything related to NLP on the LAPPS grid.'
}

protocol

The protocol keyword is used to define protocols used by web services.

Name Description
id the protocol ID.
name a human readable name for the protocol
description a description of the protocol

example

protocol {
    id 'SOAP_RPC_ENCODED'
    name 'SOAP RPC Encoded'
    description 'RPC Encoded SOAP messages.'
}
protocol {
    id 'REST'
    name 'REST'
    description 'RESTful web services.'
}

resourceMetaAttribute

Defines meta-attributes for resources.

Name Description
id the meta-attribue ID.
domain The id of the domain (as defined by the domain keyword) this attribute applies to.
name a human readable name for the attribute
description a description of the attribute

example

metaResourceAttribute {
    id 'resource.meta.size'
    domain 'lapps.nlp'
    name 'Size'
    description 'The size of a given resource'
}
metaResourceAttribute {
    id 'resource.meta.unit'
    domain 'lapps.nlp'
    name 'Unit'
    description 'The unit (KB, words, etc.) of the Size attribute'
}

resourceType

Defines the type of resource(s) that may be deployed to a node.

Name Description
id the resouce type ID.
domain The id of the domain (as defined by the domain keyword) for this resource type
name a human readable name for the resource type
description a description of the resource type

example

resourceType {
    id 'lapps.resource.corpus'
    domain 'lapps.nlp'
    name 'Corpus'
    description 'A resource that contains a single corpus'
}
resourceType {
    id 'lapps.resource.dictionary'
    domain 'lapps.nlp'
    name 'Dictionary'
    description 'A monolingual dictionary'
}

resource

Defines a single resource available on the grid.

Name Description
id the resource ID.
domain The id of the domain (as defined by the domain keyword) for the resource.
name a human readable name for the resource
description a description of the resource
copyright a copyright notice for the resource
license Licensing information for the resource
type The ID of a resource type defined in a resourceType section.

example

resource {
    id 'MASC-3.0.0'
    domain 'lapps.nlp'
    name 'MASC 3.0.0'
    description 'Version 3.0.0 of the Manually Annotated SubCorpus (MASC)'
    type 'lapps.resource.corpus'
    copyright 'Copyright 2013 American National Corpus'
    license 'Apache 2.0'
}

serviceMetaAttribute

Defined meta-attributes for services.

Name Description
id the meta-attribue ID.
domain The id of the domain (as defined by the domain keyword) this attribute applies to.
name a human readable name for the attribute
description a description of the attribute

example

serviceMetaAttribute {
    id 'service.meta.type'
    name 'Type'
    description 'Service type'
    domain 'lapps.nlp'
}

serviceType

Defines types of services available on the grid.

Name Description
id the service type ID.
domain The id of the domain (as defined by the domain keyword) for this service type.
name a human readable name for the service type
description a description of the attribute

example

serviceType {
    id 'lapps.service.datasource'
    name 'Datasource'
    domain 'lapps.nlp'
    description 'Any service that provides data to other services.'
}

service

Declares a web service that is available on this node.

Name Description
id the service ID.
domain The id of the domain (as defined by the domain keyword) of this service.
name a human readable name for the attribute
description a description of the service
url the URL used to access the service.
protocol the protocol used by the service
type The service type. Must be one of the types defined by serviceType.
copyright A copyright notice for the service
resource the resource used by the service.
license the license that applies to the service
allow the types of access that are permitted. Can be one or more of commercial, research, nonprofit
control how the service is controlled. Can be one or more of client, server
federate Indicates whether this resource can be federated. Must be one of true or false

example

service {
    id 'gate.tokenizer'
    name 'GATE Tokenizer'
    url 'http://localhost:8080/Gate/services/Tokenizer'
    description 'ANNIE tokenizer from GATE.'
    protocol 'SOAP_RPC_ENCODED'
    domain 'lapps.nlp'
    type 'lapps.service'
    copyright 'Copyright 2013 American National Corpus'
    resource 'lapps.resource.none'
    license 'GPL'
    allow 'commercial','nonprofit','research'
    control 'client','server'
    federate true
}

serviceInterfaceDefinition

Registers a service interface with the service grid.

example

serviceInterfaceDefinition {
    name 'LAPPS DataSource'
    domain 'lapps.nlp'
    type 'lapps.service.datasource'
    protocol 'SOAP_RPC_ENCODED'
    url "http://localhost:8080/DataSource?wsdl"
}

news

The news keyword is used to add an entry to the News section of the service grid user interface.

example

news 'This is some new news!'

sql

The sql keyword can be used to execute arbitrary SQL statements.

example

sql "delete from resourcetype where domainid = 'lapps.nlp'"

include

Modular LDDL scripts can be implement using the include keyword. The effect of the include keyword is the same as if the included script was pasted into the including script. Note that there is no scoping in LDDL, that is, variables defined in an included script will be available in the including script and any other scripts that are subsequently included.

example

// In config.lddl
DOMAIN = 'lapps.nlp'

// In domains.lddl
include 'config.lddl'
include 'resource.lddl'

domain {
    id DOMAIN
    ...
}

// In resource.lddl
resource {
    ...
    // The global variable DOMAIN is still available even though
    // it was not included in this script; provided the 
    // domains.lddl script is run/included before the 
    // resource.lddl script.
    domain DOMAIN
    ...
}