----------------------------------------------------------------------
		Apache Directory Server Performance Testing Archetype Documentation
		----------------------------------------------------------------------

Steps Used to Create Archetype

* Archetype Command

     The following command was used to create the archetype baseline for ADS performance testing projects:
     
     mvn archetype:create -DgroupId=org.apache.ads.archetypes -DartifactId=ads.performance.testing -DarchetypeArtifactId=maven-archetype-archetype 

* Eclipse Project Import
 
     cd ads.performance.testing/
     mvn eclipse:eclipse
     
     Now in eclipse do File > Import > and select the root directory ads.performance.testing
     and complete the import.
     
* Create the project documentation
 
     mkdir -p src/site/apt
     touch src/site/apt/documentation.apt
     
     The documentation you are reading now was generated from the
     documentation.apt file.
     
* Creating project input directories
      
     mkdir -p src/main/resources/archetype-resources/inputs/configuration
     touch src/main/resources/archetype-resources/inputs/configuration/server.xml
      
     mkdir src/main/resources/archetype-resources/inputs/ldif
     touch src/main/resources/archetype-resources/inputs/ldif/performance.ldif
     
** Input Configuration Directory Elaboration 
  
     The inputs/configuration directory now contains
     the server.xml file for configuration the ADS server.
     Every project created using this archetype gets
     this as the default configuration starting point.
  
** Input LDIF Directory Elaboration 
  
     This directory contains the baseline LDIF file used to run the performance tests.
      
*** TODO
      
     The server.xml and the performance.ldif file are currently empty
     and need to be populated.

* Remove the main/java/ directory
 
     cd src
     rm -dfr main/java

* Modify the src/test/java/AppTest.java file
 
     Change the name of AppTest.java to ADSPerformanceTest.java.
     
     Modify it so that in contains the baseline testing setup 
     and tests for ADS.
     
* Edit src/main/resources/META-INF/maven/archetype.xml
 
     The archetype.xml file tells maven which resources to include
     when creating projects of this type.
     Edit the archetype.xml file so that it looks like this:
     
------------------------------------------------------------------------------     
<archetype>
  <id>ads.performance.testing</id>
	<testSources>
   		<testSource>src/test/java/ADSPerformanceTest.java</testSource>
   	</testSources>
  <resources>
    <resource>inputs/configuration/server.xml</resource>
    <resource>inputs/ldif/performance.ldif</resource>
  </resources>
</archetype>
------------------------------------------------------------------------------     


* Edit src/main/resources/archetype-resources/pom.xml
 
 
     Change the groupId element text to:
     
     org.apache.ads.performance.testing
     
     This is now the default group id for all 
     ads testing projects of this type.
     
     
     Change the artifactId element text to:
     
     ${artifactId}
     
     Maven will now substitute the artifactId given on the commands line
     for this value.
     
     Add the additional dependencies that are needed for performance 
     testing to the this pom.
     
     These dependencies are now always included in projects
     of this type.
     
* Install the archetype in the local maven repository
 
     mvn install
 
* Create a sample performance testing archetype project
 
     mvn archetype:create -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeGroupId=org.apache.ads.archetypes -DgroupId=mavenComplainsIfWeDontGiveOneButWeDontNeedOne -DarchetypeArtifactId=ads.performance.testing -DartifactId=ads.sample.performance.testing 
     
     There will now be a performance testing project structure created called ads.sample.performance.testing.
     
     To import into eclipse, 
     
     cd ads.sample.performance.testing/
     
     and run
     
     mvn eclipse:eclipse
     
     Now just import using eclipse's File > Import

* Next Steps

** Update the dependencies on the ads.performance.archetype testing

     Add the ADS api project dependencies to the dependencies list of the performance.testing.archetype pom.
     
     This is so the unit tests can access the API.

** Create one or more baseline LDIF file(s)

    The performance.ldif file in the input directory is currently empty.
    One or more of these files should be created, such that the unit
    tests can run them.
    
    We were also discussing creating a mojo that can generate these files, or
    using SLAMD.  It would be great to have a mojo that just wrapped SLAMD,
    that way the we can just create another input directory for the file
    SLAMD uses to generate the LDIF files, and this would automatically
    be run during the generate sources phase of the maven lifecycle.

** Create the ADS Testing Setup
    
    The following setup should be done in the public void SetUp() method of each unit test contained in the peformance.testing.archetype archetype.

    * Create an instance of the server.xml configuration contained in the archetype input directory
    * Create an instance of ADS.
    * Configure the ADS instance with the server.xml instance.
    * Configure the ADS instance with the server.xml instance.
    * Run each unit test with the configured ADS instance.

** Write the ADS Unit Tests

   I think there are unit tests already, so now we just need to sanitize them so that they provide a suitable
   starting point, and put them in the archetype's unit testing directory, along with ADSPerformanceTest.java, 
   which is currently just the default test that comes with any generic maven project.

** SLAMD LDIF Generation mojo Command

     The command below will create a baseline for the ldif generation mojo:
     
     mvn archetype:create -DgroupId=org.apache.ads.peformance.testing.ldif.generation.mojo -DartifactId=ldif.generation.mojo -DarchetypeArtifactId=maven-archetype-mojo

** Completing the Mojo

    The mojo needs to perform the following activities (This is rough):
    
    * Read the configuration file for generating the ldif files (Delegate to SLAMD)
    
    * Generate the files (Delegate to SLAMD)


*** Creating another directory for the SLAMD configuration file(s)

    Please see the general instructions for creating the performance testing archetype.
    
    For now we'll assume we have the directory inputs/slamd/configuration
    available, and that it contains a baseline configuration file for generating ldif file(s)
    called "slamd.cfg".

*** Specify the location of the SLAMD configuration files in the mojo

-----------------------------------------------------------------
    private static final String SLAMD_CONFIGURATION_FILE_LOCATION = "inputs/slamd/slamd.cfg";
    private static final String SLAMD_GENERATION_OUTPUT_DIRECTORY = "inputs/ldif/;
-----------------------------------------------------------------

*** Binding the Mojo to the maven lifecycle in the performance.testing.archetype archetype  

    The ldif.generation.mojo now needs to be bound to the maven lifecycle's generate source phase.
    
    This is done in the code of the mojo:
    
-----------------------------------------------------------------------------------------------------------
    
    /**
     * @goal generate
     * @phase generate-sources
     * @description Generates the ldif file(s) and puts them in the ldif input directory
     */
-----------------------------------------------------------------------------------------------------------
    
** Updating the pom of the performance.testing.archetype archetype  

    Open the src/main/resources/archetype-resources/pom.xml and add the following build section right under the dependencies section
    (I think ADS is using JDK 1.5, so I added that to the configuration of the compiler plugin - this should be set to the 
    version of the JDK used):
    
---------------------------------------------------------------------------------------------------------
      <build>
		<plugins>
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.5</source>
					<target>1.5</target>
				</configuration>
			</plugin>
			<plugin>
                <groupId>org.apache.ads.peformance.testing.ldif.generation.mojo</groupId>
                <artifactId>ldif.generation.mojo</artifactId>
                <version>1.0-SNAPSHOT</version>
                <executions>
                    <execution>
                        <id>generate</id>
                        <goals>
                        	<goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
		</plugins>
	</build>
---------------------------------------------------------------------------------------------------------
     
* Testing the Mojo with the performance testing archetype

    The process is the same as before.  We do:
    
    mvn archetype:create -DarchetypeVersion=1.0-SNAPSHOT -DarchetypeGroupId=org.apache.ads.archetypes -DgroupId=mavenComplainsIfWeDontGiveOneButWeDontNeedOne -DarchetypeArtifactId=ads.performance.testing -DartifactId=ads.sample.performance.testing 
    
    However, now before we run tests the mojo will create the ldif files for us.
    
    Thus the file names that the mojo creates, must be used in the setup of the 
    tests.
    
    This would make it attractive to perhaps create multiple archetypes for 
    specific tests, that are just slight variations of eachother.
    
    That way we don't need to change too much stuff in the setup section 
    of each testing project.