h3. Adding your own partition resp. suffix This section describes how to add your own data partition. h4. What are partitions? In ApacheDS entries are stored in partitions. Each partition contains a complete entry tree, also referred to as a DIT. Multiple partitions may exist and the entry trees they contain are disconnected from each other, meaning that changes to entries in partition _A_ would never affect entries in partition _B_. The entries in a particular partition are stored below some naming context called the partition suffix. The default implementation of partitions is based on [JDBM|http://jdbm.sourceforge.net/|jdbm.sourceforge.net] B+Trees (but it's possible to add custom partition implementations). The ApacheDS default configuration contains a a data partition with the suffix "dc=example,dc=com". The image below shows the suffixes of a freshly installed ApacheDS within Apache Directory Studio. !partitions_in_studio_after_install.png! The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema" and "ou=system" respectively. h4. Minimal partition definition For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas". This requires editing of the server configuration stored in the ApacheDS server, and injecting a first entry, associated with the root of this partition (here, "o=sevenseas"). {info:title=Note} The way, ApacheDS handles configuration has changed with version 2.0. The configuration is now completely held in the server and can be edited with any LDAP browser or even by hand, using a text editor. However, using an LDAP browser is much more comfortable and is also recommended. {info} Open Apache Directory Studio or any other LDAP browser and connect to your ApacheDS server. Browse to the entry {{ou=partitions,ou=config}}. Below there, you will find all currently configured partitions in your server. Duplicate the {{example}} partition by copying the entry and pasting the whole _subtree_ (see image below). !copy-entry-subtree-depth-in-directory-studio.PNG.jpg|thumbnail! In the copy/paste dialog, titled "Select copy strategy", choose to _rename the entry and continue_ and set the name according to our example to "sevenseas". Click/doubleclick (depends on your settings or your LDAP browser) your newly created partition to open it for editing. Look for the attribute {{ads-partitionsuffix}} and modify its value to {{o=sevenseas}}. The new partition has now been configured - time to restart your server! Before you can use the partition (e.g. adding entries), you have to add a context entry. Connect to ApacheDS again. You can currently see the partition only in the Root DSE. The picture below shows the Properties dialog of Directory Studio for the Root DSE element after connecting to an ApacheDS instance configured like above. !properties_root_dse.png.jpg|thumbnail! Right-click the {{Root DSE}} entry and create a new _context entry_ below it. Select {{dcObject}} and {{organization}} as object classes. On the next dialog page, you will be asked for a distinguished name for the context entry. In the dropdown list the new partition suffix {{ou=sevenseas}} should have become available (image below). Select it and move on to the next dialog page. !partitionsuffix-sevenseas-in-directory-studio.PNG.jpg|thumbnail! There, enter the value "Pirates of the Seven Seas, Inc." into the {{dc}} attribute. That's it! Now you have added a new suffix and created a context entry for it. You are now ready to fill the new partition with data. As an alternative for adding the context entry manually, you can load it with your LDIF data - if you plan to load LDIF data into your partition anyway. Simply provide the context entry (the "root" of your partition) as a first data set. In our example it might look like this: {code} dn: o=sevenSeas o: sevenSeas objectClass: top objectClass: organization description: The context entry for suffix o=sevenSeas {code} It is also possible to import a file to ApacheDS which only contains such an entry, of cause. Here is an example on how to procede for the seven seas: In the LDAP Browser of Directory Studio, right click on the DIT entry and select "Import -> LDIF Import...". A file selections dialog appears. Browse to the LDIF file and click Finish. The entry (or entries, if you provide more of them) will be added to to partition. The following image depicts the partitions after reconnecting with Apache Directory Studio (_LDAP Browser_ view). !partitions_in_studio_after_adding.png! h5. Loading the context entry automatically on startup If you don't want to launch Apache Studio, or to inject the LDIF file using a command line tool, you can also tell the server to load the file when it will be laucnhed the first time. Just create an ldif file containing the context entry, and add some tag into the _server.xml_ file. For instance, you have created the *sevenSeasRoot.ldif* file containing {code} # SevenSeas root context entry dn: o=sevenSeas o: sevenSeas objectClass: top objectClass: organization description: The context entry for suffix o=sevenSeas {code} Now just modify the _server.xml_ file to add this line : {code} ... #directoryService sevenSeasRoot.ldif ... {code} The contextEntry will be loaded when the server will be started the first time. h4. More configuration options for a JDBM partition Here is a list of the used attributes, their default values and meaning || Property|| Default value || Description || | id | | (required) uniquely identifies the partition | | suffix | | (required) an LDAP DN ("dc=example, dc=com", for instance) | | cacheSize | -1 | cache size expressed as a number of entries | | optimizerEnabled | true | | | syncOnWrite | true | sync disks on every write operation | h4. Indexed Attributes The default partition implementation is based on JDBM. By default it may already index some common attributes like _objectClass_ and _ou_ for example. However you really want to index attributes that your applications use frequently in canned queries. Adding an index on an attribute is pretty simple. The configuration in the server.xml file needs to be altered before bulk loading data into the server. Otherwise your index will not work properly. {note} Indices must be configured before loading data into the server. Indices configured after loading entries into the server will NOT work properly unless they are built using the index builder command supplied with the ApacheDS tools command line program. {note} Indices are configured in the partition configuration section of your _server.xml_. Each partition will have it's own set of indexed attributes. These index configurations reside under the _indexedAttributes_ property of the _jdbmPartition_ element. Here's that section for the stock "dc=example,dc=com" partition that is configured out of the box with ApacheDS. {code:xml} ... ... {code} As you can see indices are specified using a _jdbmIndex_ element. Just add one of these to your existing configuration setting the attributeId to the OID or name of the attribute you want to index. There is cacheSize parameter used to set the amount of cache on your index as well. Most of the time 100 will suffice no matter how big in capacity your server is. {quote} This number (100) is the number of entries stored in the cache, regardless to their size. Be carefull when dealing with huge entries - those which contains jpeg images or groups with many members. {quote} So if I wanted to index the attribute *initials* all I have to do is append the following xml fragment to this set of indexed attributes: {code:xml} ... ... ... ... {code} That's it. Now queries on initials alone should perform about 50X faster. h4. Resources * Configuration Parameters Reference (to be done).