MetaBoss Programming Model Guide.

Enterprise Data Types.

Index

Definition

Enterprise Data Types are the smallest building blocks of the enteprise systems. They represent primitive business data types. Note the emphasis at the word business - too often in the programming practice primitive computing data types are confused with and used instead of primitive business data types. What is the difference ?

Instance of primitive computing data type can hold data in the range and form that are valid for particular programming language, type of processor, type of operating system etc. Number of various primitive computing data types for particular environment usually do not go far beyond ten or so (e.g. In Java : String, byte, short, int, long, float, double, boolean). These types are low level and usually have too broad range and too few restrictions to be used effectively as business data types. As a result, use of primitive computing data types to carry business data leads to having numerous places in the system, where business data type validation and conversion is performed.

Instances of enterprise data types can hold data in the range and form valid for particular kind of business data (Note that the basic principle is similar to primitive computing data types but it is applied to the different domain). For example instances of PhoneNumber enterprise data type will only be able to hold numeric string 10 digits long and refuse anything else. Number of various enterprise data types can easily run into hundreds for the large organisation.

Enterprise Data Types in Java

Every enterprise data type is represented by a dedicated Java class. This class is automatically generated by MetaBoss code generator out of the model. At the same time every attribute or field (eg. entity attributes, structure fields, message attributes etc...) are declared as being an instance of one of these enterprise data type classes. Consider following example of a data structure:

This example shows hypothetical CustomerDetails structure in MetaBoss programming model

import com.hatmaker.types.local.us.SocialSecurityNumber;
import com.hatmaker.types.local.au.DriverLicenseNumber;
import com.hatmaker.types.global.internet.EMailAddress;
import com.hatmaker.crm.types.main.PersonName;

/** This class represents a data structure containing customer details. */
public class CustomerDetails
{
    public PersonName             FirstName;
    public PersonName             MiddleName;
    public PersonName             LastName;
    public SocialSecurityNumber   Ssn;
    public DriverLicenseNumber    LicenseNumber;
    public EMailAddress           EMail;
}

As you can see fields of the structure have types declared as enterprise data types and not Java primitive types. The user of this structure does not need to validate internals of each field, knowing that an instance of enterprise data type can not be initialised with the value illegal for the type. Another example below looks at the Java method declared with use of enterprise data types:

This example shows fragment of hypothetical BankOperations interface

import com.bigbank.types.Amount;
import com.bigbank.accountmanagement.types.AccountNumber;

/** This class represents a service providing set of Banking operations. */
public interface BankOperations
{
    .....................................
    .....................................
    public Amount  getAccountBalance(AccountNumber pAccount);
    .....................................
    .....................................
    public void transfer(AccountNumber pSource, AccountNumber pDestination, Amount pHowMuch);
}

Again, inputs and outputs to the operation are declared as enterprise data types and implementations of these operations do not need to validate internals of each input parameter, knowing that an instance of enterprise data type can not be initialised with the value illegal for the type.

Another interesting feature of the enteprise data types is that they could have methods performing some sensible transformation of the enterprise data type. For example DayOfTheWeek data type may have a method toNext() and toPrevious(), which move the stored day of the week one day forward or back.

Enterprise Data Types generation

So how MetaBoss is able to generate all of these Java classes representing enterprise data types? Well, it does not! (at least not without designer). MetaBoss modelling suite provides facility to introduce new enterprise data types into the model. This process requires designer to either supply Java source for the data type or choose the template with which Java source is to be generated. This makes a job of MetaBoss code generators a very easy one - all they have to do is to copy Java code for the data type from the model definition to the generated source area. For developer it is very important to remember that bugs inside enterprise data type classes should be fixed back in the Java source or Template source stored in the model. Similarly, if anyone thinks that particular enterprise data type class needs some more convenient methods - they could be added quite easily in the Java source or Template source stored in the model.

Putting data in and getting data out of Enterprise Data Types

Enterprise data types are used everywhere throughout enterprise layers. Therefore, when working inside theese layers, there are not a lot of valid reasons to convert data between primitive computing types and enterprise data types. It is a different story at the system boundaries. Typically enterprise data type has to be created from string captured from inputs and later on the same value must be shown to human, again as string. To create instance of the enterpise data type static creators must be used as follows:

This example shows how to create an instance of the enterprise data type from java primitive

import com.metaboss.enterprise.datatypes.DataTypeValidationException; 
import com.bigbank.types.Amount;
import com.bigbank.accountmanagement.types.AccountNumber;
import com.bigbank.accountmanagement.types.AccountType;

    .....................................
    .....................................
    try
    {
        .....................................
        .....................................
        // Data types do not have public constructors. Instances must be created using static creator methods.
        AccountNumber lFrom = AccountNumber.createFromString("A234567-23");
        .....................................
        .....................................
        // Data types do not have public constructors. Instances must be created using static creator methods.
        Amount lAmount = Amount.createFromDouble(23.4);
        .....................................
        .....................................
        // Enumerable Data types expose limited set of public final static constants.
        // For these types these constants may be used instead of static creators
        AccountType lType1 = AccountType.DEBIT;
        AccountType lType2 = AccountType.createFromString("Debit");
        .....................................
        .....................................
    }
	catch(DataTypeValidationException e)
    {
        // This exception is thrown when data type creation has failed.
        System.out.println("Unable to create an instance of the data type." + e.getMessage());
    }
    .....................................
    .....................................

All enteprise datatype classes have toString() method redefined and returning the human readable string value. This value can be used for printing as is:

This example shows how to print values out of enteprise data types

import com.bigbank.accountmanagement.CustomerDetails;

    .....................................
    .....................................
    /** Prints out details of the customer stored in the structure. */
    public void printCustomerDetails(CustomerDetails pDetails)
    {
        // Printing is not much different to simple string fields.
        // Java's automatic invocation of toString() when casting object to String does the trick.
        System.out.println("FirstName   : " + pDetails.FirstName);
        System.out.println("MiddleName  : " + pDetails.MiddleName);
        System.out.println("LastName    : " + pDetails.LastName);
        System.out.println("Soc.Sec.No  : " + pDetails.Ssn);
        System.out.println("Lic. No     : " + pDetails.LicenseNumber);
        System.out.println("e-mail addr : " + pDetails.EMail);
    }
    .....................................
    .....................................
    

Common features of the Enterprise Data Types

MetaBoss provides a small abstract DataType framework. It is situated in the com.metaboss.enterprise.datatypes package and stored inside MetaBossEnterprise.jar. This framework imposes some common features on all data types. Like for example ability of every DataType to be serialised, converted to and from XML and stored to and read from JDBC data source. Please read the reference of the MetaBoss run-time library API for more details.