Creating a New Pipeline Stage

Using the Archetype to Create a New Pipeline Stage

1. Run the following Maven command in some directory

   We recommend that this directory be an Eclipse workspace directory - see Editing New Stages Inside Eclipse.

2. Choose the version of the stage archetype which corresponds to the version of Aspire which you are using.

  mvn archetype:generate -DarchetypeGroupId=com.searchtechnologies.aspire -DarchetypeArtifactId=aspire-stage-archetype -DarchetypeVersion=3.2 -DrepositoryId=stPublic

If the above doesn't work, try adding the following argument to the command:

 -DarchetypeRepository=http://repository.searchtechnologies.com/artifactory/public

It will prompt you for several input parameters:

3. After entering all of the parameters, you will be prompted to verify your selections.

Enter 'Y', and then Maven will create your new stage for you.

Editing Your Stage in Eclipse

The instructions for adding new stages to an Eclipse project can be found here:

Editing New Stages Inside Eclipse

Building Your Stage Using Maven

The aspire component is now a complete and functioning component. Note that it doesn't yet do anything useful, but it can be completely built and installed into Aspire without further modification. This is what we are going to do now.

1. To build the stage, do the following:

cd {your stage directory}
mvn clean package

2. Check the Maven output to see that unit tests and the build all complete successfully.

Changing The Source Code

Source Code

Will be in the "src/main/java" directory.

• A ready-to-compile java source file for your new pipeline stage will be located in the standard Java package directory structure. The source file will contain many embedded comments and hints for writing your new stage.

Unit Test Code

Will be in "src/test/java".

• A read-to-compile and run test program will already be in the appropriate package directory.

Other Resources

Will be in src/main/resources. Default resources are automatically provided for you by the stage archetype. These resources include:

• The ComponentFactory.xml file - Identifies the types of components that this factory can produce. Automatically set up to produce a single "default" component.
  • Note that you can put the Java code for multiple components in the same bundle/jar file. Just add more entries to the ComponentFactory.xml file as needed.
  • The ComponentFactory.xml file also contains default configuration information for each of the default types.
• Admin User Interface resources - Will be located in the src/main/resources/resources/{classname} directory. These include:
  • An image (image.jpeg) which will be displayed on your Admin UI web page
  • The status.xsl which transforms the XML status report from your pipeline stage into XHTML for display on the web page.
  • The result.xsl which transform the result XML for any web UI servlet commands that are sent to your pipeline stage into XHTML for presentation on a web browser.

Using the New Stage In an Aspire Installation

Using Maven Repositories

These instructions are appropriate when using the <repository type="maven"> setting in your Aspire settings.xml file.

Incorporate A Brand-New Component

First, make your new component available to Aspire by doing the following:

mvn clean install

Once this is done, you can then add your new stage to your Aspire System XML file:

1. Make sure you add a new <component> to the list of components for your stage
   • The factory name for the component will be your component's Maven artifact ID (e.g. "aspire-uppercase").
   • If the groupId of your component is not "com.searchtechnologies", you will also need to specify the group id in your artifact name (e.g. "com.mycustomer:aspire-uppercase").
2. Add the new stage to the appropriate <pipeline>
3. Reload your Aspire System XML file by clicking the "reload" button next to the configuration file on the http://localhost:50505/aspire Aspire application page.

If you update your component code

These updates can be dynamically incorporated into Aspire. Again, first make your new component available to Aspire with "mvn clean install". Once this is done, click on "Check For Updates" on the http://localhost:50505/aspire page. Your new component should now be flagged as "Update Available". Then click on the reload button for your component to load the new binaries into Aspire.

When Using Distribution Repositories

The following instructions are appropriate if you use the <repository type="distribution"> in your Aspire settings.xml file exclusively (i.e. for some reason you are not using the maven repository option in Aspire)

After you have written and unit-tested your pipeline stage, you can use the following steps to use your stage in a new Aspire installation.

1. Copy the component JAR file into your Aspire distribution.
   • COPY FROM: Your component's "target" directory
   • COPY TO: The Installation's "target/{distribution}/bundles/aspire" sub-directory
2. Modify Your config/system-example.xml file to include your new component in your pipeline.
   1. Inside the <component name="standard-pipe-manager">, add your component:
      • <component name="uppercaseTitle" subType="default" factoryName="aspire-uppercase" />
   2. Inside the <pipeline><stages> add your new pipeline stage>
      • <stage component="uppercaseTitle" />
3. Restart Aspire and test
   • Alternatively, you can click on "Check for Updates" on the Aspire home page
   1. Is your new pipeline stage a sub-component of "standard-pipe-manager" ?
   2. Is your new pipeline stage in the pipeline?
   3. What happens when you view your new stage in a web browser?
   4. What happens when you feed a new URL down the pipeline? (look at the end of the return of feedOne)

Exercise

Instructions: Modify the source code to convert the <title> element to all caps.

1. Explore the "src" directory structure of the component you just created.
2. Locate the java class which is the pipeline stage and modify it appropriately.
3. Locate the unit test and modify it as well.
4. Re-build the component.
5. Re-deploy it in your Aspire application.