MetaBoss Beginner's Guide
Generated source description
Overview
The source files we are describing here are created during the build and
located at the ${metaboss_home}/examples/AlmaMater/Build/generatedsource path.
The files are stored in folders and form the directory tree which mirrors the hierarchy of Java packages
(this is typical for the Java souce files). Thus, where this chapter describes the logic behind forming the directory tree
in the certain way, you can use exact same explanation to describe the naming and the hierarchy of the Java packages.
The hierarchy of the generated source directory tree is shown below:
As you can see the root of the tree is formed by the branch consisting of two subdirectories : 'com/almamater'.
This carves out the scope for all elements of the AlmaMater enterprise and keeps them independent of elements which belong to
any other enterprise. We will now describe the generated source files in more details. As we go through this description we will
refer to the elements of the Design Model which have caused gneration of particular source files. Also you may find it useful
to inspect the content of the generated files or refer to the javadoc documentation
And another bit of information to help you moving along. Most of the source code
we are about to review is organised in layers, with each layer consisting of single interface package and
any number of implementation packages. As a rule, the code of the external client of the layer operates with layer's interfaces
and does not have any knowledge, visibility or control over which particular implementation gets to serve its requests.
The actual implementation mapping is configurred in the deployment time and is resolved at run-time using JNDI based MetaBoss Component Naming framework.
The mechanism is further discussed in the System Componentisation chapter of the
MetaBoss Programming Model Guide. This 'late binding of the interface to implementation' means that
you will not be able to do a 'full round trip' and mentally step through the code along the execution path.
Index
com/almamater/types
com/almamater/crs
com/almamater/crs/types
com/almamater/crs/services
com/almamater/crs/services/coursesdomainsupport/generatedimpl
com/almamater/crs/services/coursesdomainsupport/generatedimpl/xmldevsimulator
com/almamater/crs/services/coursesdomainsupport/generatedproxy/transactionmanagement
com/almamater/crs/adapters
com/almamater/crs/domains
com/almamater/types
Enterprise directory contains one special subdirectory named 'types'.
All java classes which represent value types used throughout whole enterprise are located here. In terms of the
Design Model - every DataType located in the enteprise Design Library has corresponding java class in the enterprise types subdirectory.
For example the CourseCode Data Type which we have created in the model (the model tree path is Design Library ->Data Dictionary->DataTypes->CourseCode)
has corresponding com.almamater.types.CourseCode java class. MetaBoss programming model uses the strong datatypes approach
to all business data value types. This means that various types of business data are modelled as
individual Data Types and represented in the Java program by purpose built Java class. This approach
is further discussed in the Enterprise Data Types chapter of the
MetaBoss Programming Model Guide. The snapshot below shows contents of one of the enterprise types packages.
You may have noticed that apart from the dedicated Java class each Data Type also
has corresponding properties file. This file contains the design properties of the corresponding Data Type and
is used for run-time accessibility to the design-time properties.
com/almamater/crs
Enterprise directory contains one or more system subdirectories. Each modelled system has
distinct root directory. In our case the root of the CRM system source tree is formed by the 'com/almamater/crs' branch.
This carves out the scope for all elements of the AlmaMater's CRS system and keeps them independent of elements which belong to
any other system. If in the future we will add another system, say StaffManagement, all files pertained to this
new system would be stored under 'com/almamater/staffmanagement' and will not interfere with the files which belong to the CRS.
Each system directory contains a number of standard subdirectories which represent various architectural layers of the software.
com/almamater/crs/types
Each system directory contains the special subdirectory named 'types'. Similarly to the
enterprise types directory described above, this one contains java classes which represent value types owned by this system.
In terms of the Design Model - every DataType located in the system Data Dictionary has corresponding java class in the system types subdirectory.
For example the CourseInstanceId Data Type, which Design Studio ModelAssistant has created for us to use as unique instance identifier of the
Course (the model tree path is CRS->Public Interfaces->Data Dictionary->Namespaces->System->Namespaces->Courses-DataTypes->CourseInstanceId)
has corresponding com.almamater.crs.types.system.courses.CourseInstanceId java class.
com/almamater/crs/services
Each system directory contains the special subdirectory named 'services'. This is the root
directory of all service interfaces and implementations. It is further split into a number of directories
representing an individual servicemodules. For example, in our case the CoursesDomainSupport servicemodule, which Design Studio ModelAssistant has created for us
to use for simple Create/Read/Update/Delete operations (the model tree path is CRS->Public Interfaces->Service Modules->CoursesDomainSupport)
has corresponding com/almamater/crs/services/coursesdomainsupport subdirectory. The contents of this particular directory are shown below:
Each servicemodule directory contains following types of files:
Java interfaces with 'BS' prefix represent business services. For example in the picture above
the com.almamater.crs.services.coursesdomainsupport.BSDataManagement java interface corresponds to the DataManagement business service
which could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Services->Data Management
model tree path. The Java interface which represents a business service contains methods corresponding
to the operations cowned by the service in the model. Java classes with 'ST' prefix represent structures. For example in the picture above
the com.almamater.crs.services.coursesdomainsupport.STCourseDetails java class corresponds to the CourseDetails structure
which could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Structures->Course Details
model tree path. Structures are composite value types which have one or more other value types as members.
The Java class which represents a structure contains member variables for all members and simple accessor 'get' and 'set' methods. Java classes with 'MO' prefix represent messages. For example in the picture above
the com.almamater.crs.services.coursesdomainsupport.MOCourseVersionMismatchError java class corresponds to the CourseVersionMismatchError
message which could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Messages->CourseVersionMismatchError
model tree path. Messages are objects which represent a particular operation outcome. At the same time messages are
composite value types. The Java class which represents a message contains member variables for all members and simple accessor 'get' and 'set' methods. The Messages.properties resource file contains strings with the default text for all messages in this package.
When message objects are asked to return the message text (eg. via toString()) method, they will search for
localised resource files (eg. Messages_ru.properties for the messages in Russian language) or, if localised resource not found,
the default text from this file. The package.html file
contains description of the contents of this package and is used in generation of the javadoc documentation.
com/almamater/crs/services/coursesdomainsupport/generatedimpl
com/almamater/crs/services/coursesdomainsupport/generatedimpl/xmldevsimulator
com/almamater/crs/services/coursesdomainsupport/generatedproxy/transactionmanagement
According to the MetaBoss programming model all posible implementations of the interfaces (generated and handcoded) are located in the subpackages
of the package where interfaces are located. Subsequently all service interface implementations are located under the servicemodule package.
The contents of the 'generatedimpl', 'generatedimpl.xmldevsimulator' and 'generatedproxy.transactionmanagement' implementation subpackages discussed here are shown below:
The 'generatedimpl' implementation is "the real thing" implementation which does whatever operation was designed to do.
To generate this type of implementation it is not enough to know the service specification (ie. method names, input data, output data). One needs to have
full understanding of the validation rules, business rules, domain objects involved etc. Subsequently MetaBoss generates the
real implementation only for the trivial services it knows everything about. (Not accidentally, these are same services which were
automatically suggested by the Modelling Assistant diring design phase). In our example we have the domain administration
servicemodule called 'CoursesDomainSupport' (model path is CRS->Public Interfaces->Service Modules->CoursesDomainSupport), which falls into this category.
(Note that the real implementations for all other, non-trivial, services must be coded by hand and will be discussed later in this guide) 
The 'generatedimpl.xmlsimulator' implementation is used in testing and prototyping. It is serving operation returns from the contents of the XML files (ie. accept the operation inputs,
lookup matching XML file, read the response details and return them from the operation). This type of implementation is generated entirely from the service specification
and is available for all kinds of services (i.e. trivial and non-tirvial). 
The 'generatedimpl.transactionmanagement' proxy implementation is used to provide J2EE-like transaction management mechanism
without J2EE container. It 'wraps' around underlying service implementation and manages transaction before and after operation invocation.
This type of implementation is generated entirely from the service specification and is available for all kinds of services (i.e. trivial and non-tirvial).
Notice how all of the above implementations while very different in purpose and design, still implement the same interface.
The difference between proxy style implementation (eg. transactionmanagement) and ordinary style implementation (eg. xmlsimulator) is that the proxy implementation
passes control further down the implementation chain whereas ordinary implementation does not. In other words the ordinary implementation acts only as the server,
while the proxy implementation acts as the server and the client.
The files normally found in the business service implementation directory are:
com/almamater/crs/adapters
According to the MetaBoss programming model adapters are the client side
mechanisms helping to invoke business services from disparate platforms.
Adapters form a transformation layer between business services and business service clients.
All possible adapters for all the services from the particular system are located in the adapters subdirectory of the system directory.
Similarly to the services layer, adapters subdirectory is further subdivided to the subdirectories corresponding to
the servicemodules and various types of adapters are located in the subpackages of theese servicemodule directories.
The contents of the 'generic.stringstructures' subpackages discussed here are shown below:
The subpackage shown above contains stringstructures adapter implementation.
The stringstructures adapter is used by Java clients which do not wish or unable to work with
strongly typed value objects. This adapter exposes exact same operations as an underlying business service. The
only difference is that the primitive value fields inside data structures accepted by this adapter's methods
are always String fields (and not specialised Java classes representing Data Types). The reason behind this adapter is that we have found
that many bridging products (eg. Microsoft COM to Java or .NET to Java etc) are unable to cope with somewhat
complex albeit perfectly legal signatures of the business service operations.
Since adapter code is trying to join disparate technologies, there are no real
rules describing how adapter code should look like and what files should adapter consist of.
In fact in the extreme cases adapter may not even be written using Java language! Subsequently, the
files we describe here are likely to be found in other adapters, but this is not guaranteed nor required:
Java classes with 'ADBS' prefix represent business service adapters.
For example in the picture above the com.almamater.crs.adapters.generic.stringstructures.services.coursesdomainsupport.ADBSDataManagement
java class corresponds to the DataManagement business service adapter. The underlying business service
could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Services->Data Management model tree path. Java classes with 'PXST' prefix represent proxies to the structures.
For example in the picture above the com.almamater.crs.adapters.generic.stringstructures.services.coursesdomainsupport.PXSTCourseDetails
java class corresponds to the CourseDetails structure which could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Structures->Course Details
model tree path. Proxies to the structures contain exact same data, but in the different format. In this example
the PXSTCourseDetails proxy structure is exactly the same as STCourseDetails servicemodule structure apart from the types of the primitive value fields. Java classes with 'PXMO' prefix represent proxies to the messages.
For example in the picture above the com.almamater.crs.adapters.generic.stringstructures.services.coursesdomainsupport.PXMOCourseVersionMismatchError
java class corresponds to the CourseVersionMismatchError message which could be found at the CRS->Public Interfaces->Service Modules->CoursesDomainSupport->Messages->CourseVersionMismatchError
model tree path. Proxies to the messages contain exact same data and possibly the text message itself, but in the different format.
In this example the PXMOCourseVersionMismatchError proxy message is exactly the same as MOCourseVersionMismatchError servicemodule message apart from the field types. Java classes with 'TR' prefix ('TRMO' or 'TRST') represent translation utility classes or translators.
The translators contain public static methods to translate data between Proxy Structure or Proxy Message on one side and underlying Structure or Message on the other side.
For example in the picture above the com.almamater.crs.adapters.generic.stringstructures.services.coursesdomainsupport.TRSTCourseDetails
java class has all translation methods to copy data between PXSTCourseDetails proxy structure and STCourseDetails servicemodule structure. The package.html file
contains description of the contents of this package and is used in generation of the javadoc documentation.
In conclusion we would like to point out one very interesting artefact generated as part of
the domelements adapter. This type of adapter provides business service connectivity to
clients using org.w2c.dom objects. It offers these clients ability to call business service with
org.w3c.dom.Document input document and in response receive another org.w3c.dom.Document output document
(In other words the input and output structures are substituted by the dom documents). Obviously
the input and output documents are governed by a schema. The schema file is one of the artefacts
generated for adapter. For example the com/almamater/crs/adapters/generic/domelements/services/coursesdomainsupport/CoursesDomainSupport.xsd
schema file contains xml definition of all Data Types, Structures and Messages contained in the CoursesDomainSupport servicemodule.
com/almamater/crs/domains
System directory may contain the special subdirectory named 'domains'.
This directory contains implementations for one or more domains owned by the system and will
only be present if one or more domains (in other words databases) have been modelled inside the system.
Wast majority of the source files associated with domains are fully generated without any need for
handcoding. The business objects and domains are further discussed in the Business Objects chapter of the
MetaBoss Programming Model Guide. In our case the CRS system has Courses domain (model path is CRS->Implementation Components->Domains->Courses)
therefore the 'com/almamater/crs/domains' has only the 'courses' subdirectory with following contents:
Each domain directory contains the following types of files:
The com.almamater.crs.domains.courses.BODomain
java interface can be found in every domain. It represents the entry point into the domain and has
comprehensive set of top level domain operations. Java Business Object interfaces which represent single instance of the entity. For example in the picture above
the com.almamater.crs.domains.courses.BOStudent java interface
corresponds to the Student entity which could be found at the CRS->Implementation Components->Domains->Courses->Entities->Student model tree path.
The Business Object interface has accessor methods for all attributes ('get' for all and 'set' for user modifiable ones) and
navigational methods for all associated entities. Java Business Object Collection interfaces which represent a collection of entity instances of the same type. For example in the picture above
the com.almamater.crs.domains.courses.BOStudentCollection java interface
represents an interface to the set of Student entities (which could be found at the CRS->Implementation Components->Domains->Courses->Entities->Student model tree path).
The Business Object Collection interface has usual collection methods (such as contains(), toArray() etc) as well as
navigational methods for all associated entities. The package.html file contains description of the contents of this package and is used in generation of the javadoc documentation.
At the same time as being a place where domain interface is located, the
domain directory represents a root of the domain implementation source tree and contains following subdirectories:
- impl
this directory contains domain implementation classes.
Every Java interface from the domain interface directory has corresponding implementation class in this directory.
For example the com.almamater.crs.domains.courses.impl.BOStudentImpl java class and
the com.almamater.crs.domains.courses.impl.BOStudentCollectionImpl java class
implement BOStudent and BOStudentCollection interfaces respectively.
The generated implementation is not dependent on particular storage technology. When it comes to executing
storage operation (eg. read entity record, delete entitiy record etc.) it invokes the storage service associated with the entity.
- storage
this directory contains storage layer interfaces.
Every entity in the domain has corresponding persistence service defined in this package. The service defines
full set of operations required by domain implementation layer in order to implement all domain operations involving
particular entity (eg. create, read, search, delete etc). For example the com.almamater.crs.domains.courses.storage.PSStudent
java interface ('PS' prefix stands for Persistence Service) defines all persistence operations dealing with the Student entity from the Courses domain
- storage/mysqlimpl
this directory contains the storage code implementation layer targeting particular model
of the database - MySQL. Had we generated implementation code targeting Oracle, it would be placed in the separate dedicated 'storage/oracleimpl'
subdirectory. Generally speaking, an unlimited number of storage layer implementations can be created with each one targeting different kind of storage.
Every Persistence Service interface from the 'storage' subdirectory has corresponding implementation class in the
storage implementation subdirectory. For example com.almamater.crs.domains.courses.storage.mysqlimpl.PSStudentImpl
java class implements PSStudent persistence service interface discussed above.
|
