ART#209 - How to create an ATG repository from scratch?

Allright, we have managed great so far, and now we have arrived at a point where we are comfortable with Repository terminology involving item-descriptor, repository-items etc. and basic customization of item-descriptors.

Now, let us understand what does it take to create an ATG non-versioned repository. As we saw in article ART#201 - What is a repository?, we understood the basic repository structure. Let us re-visit those concepts in much more detail.

The repository component
Each repository always always and always has a component, which ATG resolves, just like any other component. Like each component, this component must be placed in your config-path. Also, like every component, this can also be layered.
Therefore, for creating a repository, start by creating a component and place it in your config-path. Name it "<YOUR_REPOSITORY>.properties".
Let us have a look at, what is special about this component and what all properties it requires.

a. $class
Like each component, it must have a class. Now, the good news is, you do NOT need to create this class. There is an OOTB class atg.adapter.gsa.GSARepository, which can be re-used. This class has the API for fetching/creating and updating repository items (for creating/updating/deleting/reading data to and from database). This class also has some other API, used for various other operation, but those are not significant as of now.

Now, your properties file should look like:-

Now, we also have the option of extending the GSARepository, if you want to customize some the OOTB methods is provides. You can simply extend the GSARepository class and put the new class name in the above properties file.

b. repositoryName
Set this property to any value. Generally the name of properties file itself. In our case, we can name it as "MyRepository". Your properties file now looks like:-

c. definitionFiles
This property should refer to the xml file you created for your repository. Your repository can contain many item-descriptors, which can be enclosed in a single XML file. As discussed earlier, this XML file is placed in your config-path. Please refer to the article ART#204 - How to add a new item-descriptor, to revisit the concept of XML definition files for repository.
Now, if you have created your xml file with name "myRepository.xml" at location <YOUR CONFIG PATH>/com/repository/myRepository.xml which looks somewhat like:-
Your repository component should look like:-
d. XMLToolsFactory
This property should refer to the OOTB component: atg/dynamo/service/xml/XMLToolsFactory
This component does the stuff of parsing the XML files, to make ATG understand the various mappings of tables and ites object-oriented-perspective.

e. transactionManager

Again, this property stores the reference of OOTB TransactionManager component:-
Now, if you are creating a repository, you will definitely create/update/delete the repository-items. Here is when TransactionManager comes into play. If you are familiar with database concepts, a transaction is either committed or rolled back. This property is called atomicity. Since this is not a database concept tutorial, we'll come to its significance. A repository item can have multiple properties (say 5). Now, in our java code, if we are updating all 5 of them, we would have to write 5 statements (or a single statement in a loop). Either ways, each statement would execute sequentially. Now consider a case, when the code has updated 2 properties and when it comes to update the third property, some hardware error occurs. Now, your item will be in inconsistent state, with 2 properties having new value and other 3 having old values. To prevent this behavior, these operations are enclosed in a transaction. If it fails after second statement, the entire transaction is rolled back and returned to previous consistent state. There is much much more to the TransactionManager, but above example briefly explains the high level function.

e. dataSource

This property should refer to the component:- /atg/dynamo/service/jdbc/JTDataSource/
which is present OOTB and contains connection details for your database. 
This is configured while setting-up ATG (and you do not need to worry about this, we will discuss this when we understand how we set-up ATG).
Please note that the dataSource property should refer to the JTDataSource component only for non-versioned repositories. For versioned repositories, we will study the configurations when we start with the concepts on Business Control Center (BCC).

f. idGenerator

This property should refer to the component:-
/atg/dynamo/service/IdGenerator. This component is required in cases when we want to customize the repositoryIds of an item-descriptor. For example, we want all the "order" items in OrderRepository to have a prefix "ORD", such that the order-ids become "ORD290189","ORD2891762" etc. In case of default id generation, we can simply use the component IdGenerator, without any customization. (We will learn its customization soon)

f. lockManager
This should refer to the component:-
Let us not go into the details of this one, as it has a lot to it and is beyond the scope of this article. Now, finally, your repository component should look like:-
Now, you have your database in place, your XML in your config-path and finally your full-fledged Repository Component in place, you have successfully created a non-versioned ATG repository. Let us now go ahead and understand the repository API, and how to fetch/create/update data from ATG repositories.




  1. I'm very much impressed with the way of your teaching ATG skills. So far, the concepts are explained very well and it helped me a lot to improvise my ATG skills. Your expressive language and the conceptual examples, sounds technical. I'm much more awaiting for your future releases(updates) in this blog.
    Hats off to you Monis!!!

    1. Thanks a lot for appreciation Venkat. Looking forward to writing more and more stuff!! :)

  2. Hey!!
    I am very much interested in learning ATG. Can you please help me out??

  3. Hi Monis,Thnks.very useful documents for us and can u provide Shoppingcart n BCC documents?

    1. That is on the list. Will be publishing soon.

    2. Hi Monis,

      Really awesome document and it explains so well.
      Thanks a lot for putting this together.
      Awaiting your commerce,bcc,endeca blog.




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