ART#201 - What is a repository in ATG?

We all have heard the term "repository" word before.. and came across this in almost every ATG documentation.. ATG even has a "ATG Repository Guide" which is a great reference..
In this article, will will understand what an ATG repository is, from basics.. block to block..

What is a repository?
A repository is simply an interface between your ATG application and your database. You see, on a high-level, any web application is based on two things mainly viz. source-code and database. So, what happens is, you use your source code to access database and display/create/modify some data (JDBC connections and stuff).

For now, let us say, a repository provides us with a simple-to-use interface which helps us to access data in our database. Also this repository provides us the data in Java Object form.

Why Repository? 
Can't we access data directly from database using JDBC and SQL injections?

Physically, a repository is a component with a configuration file and a class.
Like all components, some of the repositories are present out of the box, which we can customize. Also, we can create a repository right from scratch.

This component is supported by an XML file. This XML file contains the mapping of our tables to a well-defined java object. This XML mapping can club multiple tables into a single java object.
For example, consider the below table structure:-

TABLE STUDENT: (Has 4 columns)
1. student_id
2. name
3. age
4. address_id

Table ADDRESS: (Has 5 columns)
1. address _id
2. house_number
3. street_name
4. state
5. pin_code

Now, "STUDENT" table has student_id, name, age and address_id. This address_id is linked to another table, "ADDRESS" (which also has address_id). Now for this address_id, we have a house_number, street_name etc.
These are basically two tables with a single relationship (using address_id column).

If you have worked on JDBC (not required for this), you can understand that you'd have to fetch details for a particular student_id from "STUDENT" table, manually map the address_id to "ADDRESS" table via JAVA CODE and again fetch the details from this table (street name, state etc. etc.)

A repository saves you the pain for all this "linking" via java code, and provides you a single object (which you can configure), from which you can fetch all details using simple repository API (we will discuss Repository API later). 

Therefore, what the repository does for us is, it creates a wraps all the columns we require from a set of linked tables into a single JAVA OBJECT DEFINITION for all these relations, so that it is easy for us to access the database.
This JAVA OBJECT DEFINITION is called "item-descriptor". 
Also, it is we, who define what properties this "item-descriptor" must contain and which column of a table its properties map to.

Therefore, this item-descriptor is basically an XML block (written in an XML file), which contains the mapping of your database columns to the properties of the JAVA OBJECT you want to create. 

(Details on how to use/create/link these XMLs will be hashed out in later sections)

This concept is known as Object-Relational-Mapping (ORM), which maps relations in relational database to Objects.

We will get into the details for this soon enough..!

The Repository Structure!

As discussed earlier, repository is a component which is supported by an XML file. A repository component has some mandatory properties too, which have to be set.

1. Repository Component
Each repository has a component. If it is a component, it must refer to a class.
Also, it must specify the repository name.

2. Repository Class
Class used by the repository is atg.adapter.gsa.GSARepository.
(or your custom class which extends this class - rarely the scenario)

So, your repository configuration file might look like:-


3. XML File to support configuration
Each repository must have an XML file. This XML file contains all the item-descriptor definitions for the repository.  Your XML file must also reside in your config-path and must be specified in the definitionFiles property of your repository component.
These XML files are called repository definition files.

Also, you must specify a parser which understands this XML in the XMLToolsFactory property of your component. ATG provides an OOTB component for this, which you dont need to worry about. You can copy-paste the this property from below snippet.

Now, your configuration file looks like:-



4. Some important properties
Your component must be told of some other important properties. Details of which we will discuss later, when we learn how to create a repository.
For now, you can just copy paste these property values. Your configuration file looks like:-


So, this is how "basic" repository is structured. This basic structure can be changed for different types of repositories, which we will discuss soon. For now, you don't need to worry about what properties of our repository component are populated. You just need to understand the basic outline of how all this is held together.

Please feel free to put up questions in the comments below, which would help you understand this topic and help me make this article better.

Now, before we jump onto creating repositories, we must understand something very very new, which is the concept of Layering XML files. This is a very important topic, and must not be skipped if we want to understand repositories completely.

Back to Previous Chapter!



  1. Hi Monis ... These articles are very clean and clear.. I found it very useful. please if u hav resources related to atg please forward me

  2. The only resource you have in ATG is the ATG documentation. There is no book or anything which can explain that to you in a simple manner. What i write here, is just my experience, because i have struggled a lot with these things, and its very hard to get these things clear. Hence, i took an initiative to create a blog for this.
    I thank you for appreciating my effort.

    You can join the below page for latest updates on our blog. This will keep you posted.

    Cheers and Thanks,

  3. Hey Monish this tutorials are very very useful for ATG learners.Can you please post some tutorials on ATg commerce so that it would be very very useful for the commerce learner as well.your post are very easy for understanding.

  4. Hi Govind,

    Thank you for your comment. We will definitely start with the commerce part once we complete the Repository Concepts. Stay Tuned :)


  5. Monis it is a very nice tutorial .concepts are explained very simply and clearly.Thank you so much.

  6. Thanks a lot for your feedback Shalini :)


  7. Monis... your tutorial is really very helpful, informative and easy to learn. Thanks a lot for taking up this initiative. Can you please keep adding more ATG topics in the same blog itself? Also, It would be very much helpful if you could add ATG interview questions and answers for experienced as well as freshers.

  8. Hi Dhivya,

    Thanks for the appreciation. We will keep on adding more and more stuff.
    And Surely, ATG Interview questions are also on our list. Just hang around.. and you'll see the posts soon.


  9. Hi Yousuf,

    Your way of explaining in the blog is very neat and tidy.Keep up the good work.
    Also it would be great if you can list down the real time project interview questions and answers.


    1. Hi Kanchana,

      Thanks for the appreciation.
      We will be listing the interview questions real soon.

  10. Hi Monis,
    This article is simple to understand. Thank you :) Could you please tell why transactionManager and dataSource is needed in property file ? what will happen if we do not mention it?

    1. There will be a runtime error.
      DataSource is required, for the repository to know, where your tables corresponding to the repository are stored.
      TransactionManager is required as all the insert/update/remove operations should take place in a transaction.

  11. Hi Monis,

    I want to override the default value of OOTB enumerated property?
    How do I achieve this?

    Thanks in advane,

    1. It is done the same way you do it for a normal property.
      Use xml-combine = "append" for the property you want to override; and add a new < option >

      < option resource="yourNewPropertyName" code="yourNewCodeInNumerics" />

  12. I have searched all over the web for some good documentation to start ATG and stumbled on your blog. As per my opinion this is by far the best blog for ATG concepts. The notes is short and clear. Thank you very much.

  13. repositoryName vs .xml? repositoryName isn't the xml file or is it the database name?Please help

    1. It is not the database name or XML file. It is the name you want to give to your repository.

  14. very helpful...keep updating

  15. Hi Monis,

    It is a very very very useful and clean tutorial to lean ATG better. Concepts doesn't seems to be so clear and simple while reading ATG docs. The best blog for learning ATG from basics.

    Monis when are you planning to add information on BCC, CSC and Endeca ? Are these planned. Will looking forward for that information. I have started creating a blog myself for day to day errors we face while configuring Endeca with ATG will be live soon.


    1. Hi Vishal,

      Thanks for the appreciation. BCC, CSC and Endeca are coming soon. Once the commerce articles are done, BCC,CSC and Endeca will be next.

  16. I really appreciate your efforts in keeping these notes. These helped me a lot in getting back into ATG projects. Thanks



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