Proxy Classes: Building a simple proxy class

The NexJ object model provides a set of tools for modelling proxy classes. A proxy class is defined as:

The proxy design pattern allows you to provide an interface to other objects by creating a wrapper class as the proxy. The wrapper class, which is the proxy, can add additional functionality to the object of interest without changing the object’s code.

In enterprise CRM at NexJ, there are many uses for proxy classes, but the most common is building a model from which to visualize third party data that you accessed. In this article, for simplicity, we will build a proxy for data already modelled in the NexJ model. This will allow us to more easily get though some core concepts before expanding the scope to include various types of integration, the subject of future articles.

How to build a simple read-only  proxy class

As stated above, proxy classes are commonly used as a foundation from which to visualize third party data. In the majority of cases, but not exclusively, this data is read-only. Fortunately, a read-only proxy is much easier to implement than fully CRUD enabled proxy. To build a read-only proxy we follow these steps:

1. Create a new class in the NexJ business model and add attributes to that class.
2. Set the class to be service persisted.
3. Map the class attributes to the persistence layer.
4. Implement a read case and read script.

To help illustrate these steps, we will  create a proxy class which summarizes the number of people in a certain tier. We will name the class PersonByTier.

1. Creating the class

Create a new class using NexJ Studio. Give it the name PersonByTier. Add the following two attributes.

2. Set the class to be service persisted.

In the class editor, click the Persistence Mapping tab. Normally, we set the data source to be one of the relational data bases sources, but in this case we select Service. This is sort of like creating a custom data source for just this class.

3. Map the class attributes to the persistence layer.

Still in the Persistence Mapping tab of the class editor, click the Object Keys subtab. Here we can set singular or composite keys for this proxy. In this case, we will create a singular key as we are not establishing relationships with any other proxy classes.

Click the + button and type “binary” into the Type field of the newly created row in the Object Keys list.

Now click the Attributes Mappings tab. This is where we will provide the actual attribute persistence mappings.

Click the Select Attribute Mappings button. In the Select Attribute Mappings dialog, click Add All and then click OK. You now have properly service persisted attributes in your class.

4. Implement a read case and read script.

The bulk of the work in creating a read-only proxy class falls within this step. Here you will access the data that you want, potentially manipulate it, and then create a collection of transfer objects which the framework will convert into instances of the proxy class.

In the Persistence Mapping tab, click the Read” subtab. Notice that the contents of the tab are split into two panes. The top pane is a list of Read Cases, and the bottom pane has a Read Script and a Close Script. Here we can implement a custom read for various where clause patterns. You might do this if you need to call different APIs depending on how the data is to be filtered. For our case, we are going to implement a blank where clause that will handle all cases and pass the where class through to a single read script.

Click the + button to add a Read Case. We will now discuss implementing the read script on the Read Script tab.

Writing a Read Script

For a basic read script, there are three main parts:

1. Read some data.
2. Manipulate the data.
3. Create a collection of transfer objects and return the collection.

For our class we want to summarize some data, so we will perform an aggregate read on the Person class.

This will return a collection of objects with two attributes: tier and numPersons. The tier attribute is an enumeration and the numPersons attribute is an integer. Since we have modelled tier as a string in our class, we will need to grab the caption from the value of tier. We normally do this with the following  snippet, which is treating inst as if it is an instance returned by the above aggregate read.

We then need to create a collection of transfer objects containing the data returned but the aggregate read. The resulting collection would look something like this.

Of course writing the code like that doesn’t really make sense as what we are practically doing is looping through a result set and creating the collection of transfer objects as we go. The actual read event should look like the following.

This gives us our basic proxy class which we can now use to perform a read. Start up your server console and give it a try.

I hope the helps give you a basic understanding of building proxy classes. Soon to follow will be more articles explaining more advanced features of proxy classes.

Attached to this article is the sample class used as an example.

Download PersonByTier.meta