Maynstall Database WebServices

Introduction

Within Maynstall, there is a layer of database services which allow a JPA-style data model to be exposed via REST-style web services. These services provide a consistent client-side representation of the POJOs including the ability to modify objects on the client and then persist a transaction of changes to the server. The services also include the following:

• Background loading of related objects upon reference to those objects
• Blocking and non-blocking with events mode of loading data not yet available on the client
• Meta information to inspect pending changes on the client side
• Usage of JPA annotations to support understanding inter-object relationships
• Default JPA provider on the server providing integration with JPA (aka EclipseLink) to automatically expose any object
• Security interceptors to restrict reading, updating, deleting and creating objects based on user and/or attributes being changed
• Registration of model providers allowing mixing of objects from remote WS-based services as well as local JPA DB connections
• Triggers for loading a large portion of the model in a single request for optimization
• Procedures that can be registered via extension point to allow complex Java implementations of queries on the server
• Out-of-band loading of large binary attributes as well as out-of-band uploading of binary data avoiding expensive serialization in the XML payloads
• Lazy loading of large binary attributes with out-of-band download
• Custom depth specification to control amount of data retrieved upon access to an object

Getting Started

To get started with the Maynstall database layer for remote objects, use the attached project set on this Wiki page. It provides you with the right set of projects that you need to work with the services. Note you will also need to EclipseLink or another JPA provider in your workspace / Eclipse install to allow the Maynstall code to resolve the various dependencies.

Download Team Project Set - Media:MaynstallDBWS-projectSet.psf

Overview of Plug-ins

org.eclipse.maynstall.client.core

Provides base services for using REST-style web services, and in particular, services that are backed by a Maynstall-based server side (provides simple services for accessing and sending requests)

org.eclipse.maynstall.client.model.provider

Registers a provider of Maynstall model contexts that is backed by a remote set of web services including providing transactional commits over the loaded data model.

org.eclipse.maynstall.common.tracker

Required to support a dependency in org.eclipse.maynstall.common.ws, not technically used by the Maynstall database web services.

org.eclipse.maynstall.common.type

Provides a set of common types used on the client and server side by the data model and data services. Also includes a few references to enums used by the Maynstall provisioning technologies (and is not directly required by the Maynstall database web services).

org.eclipse.maynstall.common.util

Provides common utilities leveraged by Maynstall services including services for calculating checksums, dealing with DOM, and accessing files used to configure Maynstall.

org.eclipse.maynstall.common.ws

Provides a set of common web service abstractions for building REST-style web services; mainly used as an underlying layer for the data services supported by Maynstall, but can be used as a building block for other REST web services as well.

org.eclipse.maynstall.model.core

Provides the main abstraction of the IModelContext and supporting classes which can be used on the client and server side for accessing content from different providers, including remote REST-based provider, and the JPA provider.

org.eclipse.maynstall.model.provider.common

Provides the common abstractions used by the different providers to implement the different mechanisms (including custom) model objects.

org.eclipse.maynstall.server.model.provider

Provides a JPA implementation of the model provider for leveraging JPA model objects via both the Maynstall model context paradigm as well as typically tied in to the model provider web services for access from a client.

org.eclipse.maynstall.server.model.provider.ws

Provides a set of web services to support usage of any model providers remotely via REST-style web services including typical CRUD style object access simply using the JPA annotated objects.

org.eclipse.maynstall.server.persistence

Provides base services for using JPA models within the Maynstall web service abstractions.

Coding with the Maynstall DB Access

Step 1: Creating your Model

To get started using the remote Maynstall DB access, you must first create your JPA-annotated POJOs that will be made available remotely via Maynstall. When doing this, note that Maynstall respects relationships like OneToMany, ManyToMany, etc. and these must be specified to allow Maynstall to correctly understand the relationships when sending the information to the server side (and when serializing the content back to the client).

Also, Maynstall intercepts the access to the various methods on the model objects. If you are going to implement utility methods on your POJOs, it is currently necessary to use the @ComputedAccessor annotation to flag that certain methods should be left as is, and not attempt to use the lazily loaded model that Maynstall is handling behind the scenes.

This is an area of potential improvement in Maynstall since the code could better understand the field-level definitions to determine what calls / accessors should be intercepted and how.

Step 2: Setting up your model mappings

In Maynstall in each process you have, you can independently map your model to providers. For instance, on the client-side of your application, your model can be mapped to the remote REST-style service whereas on the server, you can map your model to JPA. On either side, if you then use IModelContext, you can access the model objects independently of concern for whether objects are on the client or server. There are extra annotations that can be specified on the object, such as model loading triggers that may only be used on one side of the client.

  <extension
        point="org.eclipse.maynstall.model.core.modelContext">
     <modelContext
           Id="MyClientModelContext"
           provider="org.eclipse.maynstall.client.model.provider.DefaultClientModelContext">
     </modelContext>
  </extension>
  <extension
        point="org.eclipse.maynstall.model.core.modelObjectSet">
     <modelObjects
           modelContext="MyClientModelContext">
        <modelObject
              class="com.foo.bar.User">
        </modelObject>
     </modelObjects>
  </extension>

The code above maps the com.foo.bar.User object back to the default client-side model context which uses REST-style web services to retrieve objects from the server.