Skip to content

Martini Data Models Object Types

Introduction

Data models in Martini are similar to JavaBeans, as they consist of fields or properties. This section explores the various property types you can add to a data model in Martini and the kinds of objects or values they can store.

An object in Martini is an instance of any of these types. Martini objects, irrespective of their type, have additional properties known as meta-properties. These meta-properties play a crucial role in enabling interactions with various data formats like XML, JSON, and YAML, enhancing user interfaces in the Martini IDE, and providing a clearer representation of APIs when exposed as REST and SOAP web services.

Available Object Types

Martini's data modeling capabilities allow for incorporating a wide range of property types in a model. The following table lists the different object property types, ranging from basic types like String and Integer to more complex ones such as Model and Object. The Object type is especially flexible, enabling references to Java or Groovy objects by specifying their class name.

Table: Object Types and Their Java Equivalents

This table outlines the object types available in Martini and their corresponding wrapped Java equivalents, which is essential for understanding the interaction between Martini types and Java types.

Martini Object Type Wrapped Java Equivalent
BigDecimal java.math.BigDecimal
BigInteger java.math.BigInteger
Boolean java.lang.Boolean
Byte java.lang.Byte
ByteArray byte[]
Character java.lang.Character
Date java.util.Date
Double java.lang.Double
Float java.lang.Float
Integer java.lang.Integer
Long java.lang.Long
Model N/A
Object java.lang.Object
Short java.lang.Short
String java.lang.String

Meta-properties in Martini Data Models

Overview

In Martini, meta-properties are additional attributes that enhance the functionality of objects within data models. They play a vital role in self-validation of objects and data models, as well as in reading and writing data in various formats like XML, JSON, and YAML.

Each object type in Martini supports a specific set of meta-properties. This section outlines these meta-properties and indicates which object types support them. Understanding which meta-properties are available for each object type helps in effectively using Martini for various data integration tasks.

Supported Meta-properties Table

The table below details the meta-properties and indicates which object types support them. An 'X' marks the support of a meta-property by a particular object type.

Object type Name Alias Comments Default Value Required Allow Null Array Minimum Array Size Maximum Array Size Validation Expression Output Expression Namespace URI Choices Allow Other Values Minimum Maximum XML Attribute Date Formats XML Type Allow Extra Properties Reference Object Class Name Minimum Length Maximum Length
BigDecimal X X X X X X X X X X X X X X X X X
BigInteger X X X X X X X X X X X X X X X X X
Boolean X X X X X X X X X X X X X
Byte X X X X X X X X X X X X X X X X X
ByteArray X X X X X X X X X X X X
Character X X X X X X X X X X X X X X X X X
Date X X X X X X X X X X X X X X X
Double X X X X X X X X X X X X X X X X X
Float X X X X X X X X X X X X X X X X X
Integer X X X X X X X X X X X X X X X X X
Long X X X X X X X X X X X X X X X X X
Model X X X X X X X X X X X X X
Object X X X X X X X X X X X X X
Short X X X X X X X X X X X X X X X X X X
String X X X X X X X X X X X X X X X X X

Understanding the Role of Meta-properties

Meta-properties in Martini serve several key functions:

  • Self-Validation: They enable objects and data models to perform self-validation, ensuring data integrity and consistency.
  • Format Compatibility: They facilitate the correct interpretation and formatting of data when interacting with various data formats, such as XML, JSON, and YAML.
  • Enhanced UI and API Representation: Meta-properties help enrich the user interfaces

in Martini and provide more descriptive representations for APIs when exposed as web services.

Specific Meta-properties and Their Use Cases

  • Name and Alias: Useful for naming conventions and alternative references.
  • Validation and Output Expressions: Allow for custom validation rules and output formatting.
  • Min/Max Values and Lengths: Set boundaries for numerical and string types.
  • Array and Its Constraints: Define array-based properties and their size constraints.
  • XML and Date Formats: Customize how data is represented in XML and how dates are formatted.

Detailed Descriptions of Martini Meta-properties

Name

The Name meta-property represents the variable name of an object in Martini. This name is what appears in the Martini user interface and is typically used for accessing the property in Groovy code. It's equivalent to a variable name in traditional programming.

  • Handling Reserved Keywords and Invalid Names: If the name chosen is a reserved Java or Groovy keyword, or if it's invalid as a Martini variable name, the Alias meta-property comes into play. The original name is preserved in the Alias and used for serialization, while the Name in the Martini UI and Groovy code is modified (usually prefixed with an underscore).

Alias

Alias is used when the normal Name is not suitable for serialization. This could be due to invalid characters or sequences for formats like JSON, XML, YAML, etc. In such cases, Martini sanitizes the name for use in code, while the alias is used for serialization.

  • UI Representation: In the Martini interface, when a property requires an alias, it is shown next to the name in brackets. The alias dictates how the property is named in JSON/XML representations, while the sanitized name is used in Groovy code.

Comments

Comments in Martini serve as documentation for each object. They provide additional information and context, and are visible in the Martini UI following the property name.

  • Integration with API Documentation: These comments are not just for internal documentation; they also automatically populate in the API files, enhancing the understandability of APIs.

Default Value

The Default Value meta-property specifies the value to use when an object has no actual value (null). It's akin to initializing a field with a default value in Java.

  • Applicability: This meta-property is applicable to all Martini object types except for Data Models.

Required

The Required meta-property indicates whether a variable should be included in the serialized output (XML, JSON, YAML), even if its value is null.

  • Serialization Behavior:
  • If Required is true, the variable is serialized even with a null value.
  • If Required is false and the value is null, the variable will be omitted from serialization.

Allow Null

Allow Null determines whether an object can have a null value. It is a critical validation step in Martini's runtime processing.

  • Validation and Error Indication: During runtime, if an object marked as not allowing null (Allow Null: false) is null, an exception is thrown. In the Martini UI, such properties are highlighted for easy identification, and errors are displayed during the development phase if a null value is detected.

Array

The Array meta-property in Martini indicates whether a property should be treated as an array. This feature is essential for managing collections of items within data models.

  • Implementation: When a property is marked as an array, Martini internally uses a java.util.List to manage these properties. In the Martini UI, array properties are visually distinguished by array brackets on the bottom right corner of their icon.

  • Flexible Mapping: Martini supports flexible mapping strategies between arrays and non-arrays. When mapping an array to a non-array, the first element of the array is used. Conversely, mapping a non-array to an array results in the non-array value being the first entry in a new, cleared array.

  • Array Toggling: Users can toggle the array status of a property in Martini through different methods, including the 'Convert To' context menu option and the Properties table.

Minimum Array Size

The Minimum Array Size meta-property sets the required lower bound on the size of an array property. Martini performs this validation before invoking services.

  • Validation Logic: If an array property's size is less than the specified minimum, Martini throws an exception to enforce this constraint.

Maximum Array Size

The Maximum Array Size meta-property sets the upper limit on the size of an array property.

  • Validation Logic: An exception is thrown in Martini if the size of an array property exceeds the defined maximum limit.

Validation Expression

The Validation Expression meta-property in Martini enables the creation of custom validation rules for an object's value.

  • Language Support: These expressions can be crafted in any scripting language compatible with Martini.
  • Application to Arrays: When dealing with array properties, Martini evaluates the expression for each item in the array.
  • Outcome Expectation: The expression is expected to return a boolean value, determining the validity of the checked value.
  • Variables Provided for Validation:
    • object: The object currently being validated.
    • val: The specific value that requires validation. For Kotlin, _val should be used due to 'val' being a reserved keyword.
    • index: If the property is an array, this variable denotes the index of the current item. For non-array properties, it is null.
    • collection: This represents the actual list (java.util.List) for array properties. It's null for non-array properties.

Example Validation Scripts

  • Current Year Validation: 

    1
    new Date().getYear() == val.getYear()

  • Even Number Validation: 

    1
    val % 2 == 0

Enhanced Output Control and Enum-like Behavior in Martini

Output Expression

The Output Expression meta-property in Martini plays a pivotal role in formatting object values for different output formats like flat files, XML, JSON, and YAML. It's especially useful for customizing the representation of data in various serialization formats.

  • Flexible Formatting: This property allows for dynamic formatting based on the output type. For example, you can format numbers differently for JSON and XML, or add specific prefixes for text or Excel files.
  • Expression Examples:
    • Format values differently for each output type: 
      1
2
3
4
5
6
7
8
      def expressions = [
    xml : val.toString().toLowerCase(),
    json : val.toString().toUpperCase(),
    csv : val.toString().trim(),
    txt : "Hello $val",
    xls : "Excel says $val"
]
return expressions[type]
    • A simpler expression for uniform formatting across all types: 
      1
      val.toString().toLowerCase()
  • Variables Provided:
    • Object: The actual object being processed.
    • val: The value to format.
    • index: Index in the array, if applicable.
    • collection: The actual list for array properties.
    • type: The output format (e.g., txt, csv, xml, json, yaml).

Namespace URI

The Namespace URI meta-property is utilized when converting objects to XML. Martini leverages this property to declare XML namespaces where necessary, ensuring proper structure and readability in XML outputs.

Choices

The Choices meta-property allows an object to function similarly to an enumeration (enum) in Java. It restricts the values that an object can accept, providing a predefined list of acceptable values.

  • UI Integration: Martini utilizes this property by displaying a list of choices instead of a standard text area when setting values, simplifying the selection process for predefined options.

Allow Other Values

This property complements the Choices meta-property by determining whether values outside the predefined choices are permissible.

  • Behavior Control:
    • If set to false, Martini throws an exception when a value not included in the choices is set.
    • If true, Martini displays both the list of choices and a text field, allowing for the input of values not predefined in the list.

Minimum

The Minimum meta-property sets the lowest permissible value for an object. During runtime, if an object's value falls below this minimum, Martini will trigger an exception. This feature is crucial for ensuring data stays within defined boundaries.

Maximum

Similarly, the Maximum meta-property defines the highest value an object can have. If an object's value exceeds this maximum at runtime, Martini will throw an exception. This control is essential for maintaining data integrity within specified limits.

XML Attribute

The XML Attribute meta-property determines if an object should be marshalled as an XML attribute. When this property is set to true, an attribute badge is displayed on the object's icon in the Martini interface, providing a visual cue of its XML representation.

Date Formats

For objects of type Date, this property allows for flexible parsing of date values. When a Date object receives a value of type java.lang.CharSequence, it iterates through a list of Java DateFormat patterns to find a compatible format for conversion to a Date object.

XML Type

The XML Type meta-property specifies how Date or String values are written in XML format. This property can take various values, each corresponding to different XML date and string formats, allowing for precise control over XML serialization.

  • For Dates: Possible values include dateTime, date, duration, time, gYearMonth, gMonthDay, gYear, gMonth, gDay, or null.
  • For Strings: Options are normalizedString, token, or null.

Allow Extra Properties

Setting this property to true enables a Data Model to dynamically add new properties at runtime, functioning similarly to an 'Expando' class in many programming languages. This feature enhances the flexibility of data models in Martini.

Reference

The Reference meta-property is used when a model needs to inherit properties from another model. In Martini, this equates to referencing or extending another model, similar to the concept of inheritance (extend) in Java. Combining this with Allow Extra Properties set to false is akin to creating a 'final' class in Java.

Object Class Name

Specific to Object types, this meta-property defines the class name of the value stored by the Martini Object. It is used when storing an object that is incompatible with other predefined object types in Martini.

Minimum Length

Applicable only to String types, the Minimum Length meta-property sets the minimum length requirement for a String value. This feature ensures that strings meet specified length criteria.

Maximum Length

Also specific to String types, the Maximum Length meta-property establishes the maximum length that a String value can have. This control is vital for maintaining expected string size constraints.