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:-
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.