ART#204 - How to add a new item-descriptor to out of the box non-versioned repository?

Creating an entirely new item-descriptor is pretty easy once you know the process to add a new property to an existing OOTB item-descriptor. Before starting with this article, please refer to the PREVIOUS ARTICLE which explains a lot of concepts on repository extension.

Before we jump onto the syntax, we must first hash out the design for our very own item-descriptor. We need to understand clearly on what properties we want for this item-descriptor. Generally, we can create an item-descriptor using a single primary table, but it depends on your requirement. In case, if your item-descriptor has a property which is a set or a list, you might have to create an extra auxiliary table to complete your task.

Earlier in previous article, we took an example of ProfileAdapterRepository, we will extend the same repository here too.Let us consider a following example to understand the creation of a new item-descriptor. Nowadays, every physical store gives you an option to opt for a card, wherein you can store points with every purchase and then redeem those points. (For example, store gives you a card an says, "Sir, you'll receive 1 point on every purchase of $100. And every point is equivalent to $1. So when your points reach a minimum of 20, you can redeem it to buy any item above $20".

So first, we need to hash out some of the design details:-

1. We need an item-descriptor name. We name it as "pointsCard".
2. Next, we need to make some tables for this.
3. Next, we find out what our table name should be. We name it as "POINTS_CARD".
4. Now, we need to find out what this table should contain.
5. Our table should have the following columns:-

  • ID (type- String): Every item-descriptor should have an id-column, which stores a unique id for each item of this item-descriptor. (You can also name it as CARD_ID, there are no restrictions on names). This would also be the primary key of our table.
  • USER_ID (type - String): You can optionally wish to store a user_id in this item-descriptor, to make out, which user holds this "pointsCard". (At repository-xml level, we can configure it to be a "user" item, rather than a plain string id)
  • CARD_NUMBER (type - String): This field should be present to store the card number of this card.
  • EXPIRY_DATE (type - timestamp): This stores the expiry date of the card, i.e. till when it is valid.
  • CARD_POINTS (type - int): This store the points present in the card at a particular time. These points can increase with purchase and decrease with redemption (or simply lapse or become zero after expiry).
  • LAST_MODIFIED_DATE (type - timestamp): The only thing which can be modified in this card with time, is "CARD_POINTS". No other details can be modified after initial setup of the card. This column would store a time-stamp of last activity on the card.
See below screenshot for details:-

6. Next, we create a sql-script for our table structure. Below is the sql:-

7. Now that we have created a SQL, we need to write the XML for this item-descriptor in "userProfile.xml". For details on this file, you can refer to the PREVIOUS ARTICLE. Now, you add the following stuff in your XML. See below screenshot for details:-

Now, your item-descriptor is ready to go, and you can store data in it easily. The best part is, you do not have to write explicit java code for updating "lastModifiedDate". It will be taken care by repository itself. 
Also, repository does the task of fetching the "user" item-descriptor by itself, using the "ID" present in the USER_ID column of our table. See the description of "userId" property in above screenshot.
Now that we have understood the concept of creating a very very basic item-descriptor, we can go on to understand the concepts of one-to-many and many-to-many mappings in item-descriptors. The example we saw above was for one-to-one mapping.
We will continue with the same example in our next chapters, with variations based on the type of mappings.




  1. Hi Monis
    Thank you very much for your effort. Really very helpful.

    I've few queries. Please do help me understand as I'm very much new to this learning.

    1. From this and last chapter, I'm finding that no class has been created. Is this just left out and not mentioned or ?
    2. And also for extending repositories extending XML is shown. But then config files still need to be updated right? To mention new class?
    3. If we use the approach of changing definitionFiles in config file, should not that be using += instead of =?
    4. Why do say follow xml approach and not config approach to extend repos? Any specific reason?

    Please help me understand these.

    Thanks and Regards

    1. Hi Aravind,

      1. This article describes adding a new item-descriptor in EXISTING repository. This means the configuration/classes etc. have already been created.
      Please refer to ART#209, for understanding how a new repository is created. [It has all the steps you are asking for]
      For creating a new repository, we use an out of the box class: $class=atg.adapter.gsa.GSARepository

      2. NO. If a repository is existing, this means the config files are already created, and config files already refer to an "XML" file which contains the repository definition.
      You simply have to override the repository XML in your config layer to make it work. No other changes are necessary.

      3. NO. You are "CHANGING" a property, which means you dont need the value of previously set property. Therefore "=" will do just fine.
      "+=" is used in case of Arrays/Sets/Lists etc, when there are some properties already mentioned OOTB, and you want to APPEND, some more property values in your layer.

      4. Following XML approach is easy, more readable and easy to debug. Plus, you'll be saved from doing other configurations.

  2. If an item descriptor has say 3 tables and all three table maintain last-updated property separately then can we still use last-modified-property?

    1. No. In an item-descriptor, nomatter how many tables you add, the property names should be unique. You have to choose one property out of them and add it into "last-modified-property".
      If you want to update other tables too; in that case either create a new item-descriptor for those tables and add it as a property (one-to-one mapping). OR if this is not an option; manual code is the way to go.

  3. This example explains about adding a new item-descriptor for OOTB repository. But, for order repo, we need to create a beanNameToItemDescriptor map. In that case, we would create a bean class for the new item-descriptor, right? How to handle that scenario?

    1. Those details are present in commerce section, please visit that.



Get All The Latest Updates Delivered Straight Into Your Inbox For Free!