Page History

...

During the last DSpace Committer meeting, I was prodded to start to show the community how one uses the Service Manager with some real world examples, .  I've decided to start to create a few of these HowTo's to assist you in learning to use the DSpace Services in intelligent ways.  I had this little project floating around for some time and I decided it was something I could get down on paper fairly quickly for you.  DSpace Services are about using Spring to Simplify your development life. And for our first example showing how to create services we will refactor the DSpace Launcher to no longer utilize the launcher.xml and instead load configured Commands commands from a spring Spring configuration.  The result of this approach will allow for Addons to easily provide additional commands into the launcher without having to physically alter a configuration.xml file in a config directory.  To start with we will review the ScriptLauncher and discuss the problems that exist with it. For a full view of the source please see: ScriptLauncher.java

DSpace Legacy ScriptLauncher

First and formostforemost, we see that ScriptLauncher begins the process of execution by bringing the ServiceManager into existence.  This is important so that services are available to the executed commandline tools , — these services currently wire discovery and statistics into dspace.  

...

But, here, we just focus on what ScriptLauncher itself is doing and how we can improve it with services. So looking further on we see that we parse the xml XML file with JDOM and use xpaths XPath to navigate the configuration, which means if we want to do anything new in the Launcher in the future, we may need to extend the XML file and alter the parsing. So, what we do see is that execution of the Commmand commmand is very tightly bound to the parsing and iteration over the xml XML file , — in fact, they are so tightly bound together that new code would need to be written if you wanted to get a commands command available outside the launcher.

...

                    if ((args.length == 1) || (("dsrun".equals(request)) && (args.length == 2)) || (!passargs))
                    {
                        useargs = new String[0];
                    }
                    else
                    {
                        // The number of arguments to ignore
                        // If dsrun is the command, ignore the next, as it is the class name not an arg
                        int x = 1;
                        if ("dsrun".equals(request))
                        {
                            x = 2;
                        }
                        String[] argsnew = new String[useargs.length - x];
                        for (int i = x; i < useargs.length; i++)
                        {
                            argsnew[i - x] = useargs[i];
                        }
                        useargs = argsnew;
                    }

The Big Problem : The ScriptLauncher hardwires XML Configuration to Business Logic

What we see is that the Script Launcher hardwires all Business Logic to XML configuration, and while this is a great prototype, certainly not very extensible.  For instance, what if we may want to initialize other details into the command or step?  What if we are calling something that uses a different method than a static main to execute?  and what if we want to set certain properties on its state beforehand. ? To do these tasks we would either need to rewrite the class with a main method, or we would either need to extend the launcher to do this, or add those details from the dspace.cfg. So what we will show you in refactoring this code is that you can get a great deal more flexibility out of Spring with a great deal less work on your part. Spring applies the concept of "inversion of control". The Inversion of Control (IoC) and Dependency Injection (DI) patterns are all about removing dependencies from your code.  I  In our case, we will be removing a dependency on the  hardcoded xml XML file for configuration and liberating the Command/Step domain model from the ScriptLauncher, allowing for possible reuse in other areas of the application.

...

Firstly we recognize that we have few domain objects here that we can work with, : Command, Step and Arguments are all ripe to be defined as interfaces or implementation classes that capture the domain of the Launcher that we will execute.  Perhaps by creating these we can disentangle the Business logic of the Launcher from its configuration in xmlXML.  Doing so without Spring, we might still ahve have to bother with parsing the xml XML file.  So with Spring we get a luxury that we no longer need to think about that.

We will do this initial example directly in the dspace-api project so you do not get sidetracked in terms of dealing with Maven poms....

Step 1: Domain model

Command

Command holds the details about the command we will call. Notice it doesn't parse any xml XML and most importantly it does not instantiate any Step directly, ; that is decoupled from the Command and we will show you later how it is assembled. All Commands {{Command}}s do when getting created is sit there like a good old JAVA Java Bean should. It just "IS".

package org.dspace.app.launcher;

import java.util.List;

public class Command implements Comparable<Command> {

    public String name;

    public String description;

    public List<Step> steps;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

    public List<Step> getSteps() {
        return steps;
    }

    public void setSteps(List<Step> steps) {
        this.steps = steps;
    }

    @Override
    public int compareTo(Command c){

        return name.compareTo(c.name);
    }
}

Step

Step will be responsible for retaining the details about the step being executed, you . You will notice it knows nothing about a Command, and in our default case , it just know knows a little bit about how to reflectively execute a Main Class.  Again, it knows little about its instantiation nor anything specifically on how it is configured. It just "IS".

...

Step 2: The Command Service

Ok at this point your probably itching you're probably itching to combine all these together and get your Launcher to execute.  But at this point, well, we still have some more work to do to get ready.  And likewise, we are still keeping completely hands off of any configuration detail at this point. Do not worry, we will get there soon enough.  

Next we have the CommandService, this . This is a "Controller" which you will use to execute a Commnad, it Command. It doesn't have a main method, because, well, you can execute your commands entirely independent of a CLI, wouldn. Wouldn't that be nice in Curation Tasks and Filter Media? Yes, sure it would, but I digress, lets get back to the topic at hand. The Command Service...

All it will do is contain the buisness business logic to call a command.  In this case, you will see, it just has no clue at all how it gets those commands, but it surely just understands how to execute them, pretty smart little service, it just does what its told. Doesn't think about much else.

...

package org.dspace.app.launcher;

...
public class ScriptLauncher
{

private static transient DSpaceKernelImpl kernelImpl;

public static void main(String\[\] args)
{

...

CommandService service = kernelImpl.getServiceManager().getServiceByName(CommandService.class.getName(),CommandService.class);

...

try {
            service.exec(Arrays.copyOfRange(args,1,args.length));
        } catch (Exception e) {
            ...
        }
 
...
}

}

Ok, at this point your saying. Butyou're saying, "but, wait a second, how did you configure the CommandService, Commands and steps {{Command}}s and {{Step}}s so they could be available.  Thats ?"  That's the majic of Spring, and theres there's a couple ways we do this, but I will take the most explicit approach that still will allow you to wire in your own Commands {{Command}}s later.

Step 4: The Spring Configuration

...

This location allows us to "augment the existing services without actually overriding them", we . We generally reserve this for the core dspace DSpace services like RequestService, ConfigurationService, SessionService, etc.

Wiki Markup
spring-dspace-addon-\[a unique name\]-services.xml

This location allows us to "override" the XML loading a specific service by overwriting its configuration in one of our own.

Now to show you our Launcher Service. The trick here is we will use a feature in Spring called , autowire byType, it . It will collect all the Commands {{Command}}s and wire them together for us, not no matter the type. I'll save you having to view the whole file , — you can see it here if you like .

...

You'll notice we now have created the ScriptLauncher Service via a bean definition

 <!-- Instantiate the Launcher Service and Autowire its dependencies -->
<bean class="org.dspace.app.launcher.ScriptLauncher" autowire="byType"/>

And that we have created the Command for the Checksum Checker here...

...

You also recall that with DSpace we have a DSRun command that gives us a different behavior that normal commands, : it rather wants to recieve receive the class, rather than defining it itself, so we exended Step and introduce a special Step in DSpace that just knows how to do that.

...

So yes again, we made sure that our DSRUNStep is smart and simple minded, it . It just knows how to do one thing very well, thats that's execute a class passed as an option on the commandline. It does it smartly reusing a generic Step and setting all those values it needs within it.

...

One of the luxuries we get from using the autowire byType in our spring configuration within the ServiceManager, is that now we can allow others to toss in their commands regardless of what they are named — we just need to know that they implement our Command interface and provide Steps {{Step}}s we can execute.  For instance, to introduce a command that will allow us to index discovery or operate on teh the statistics indexes, we can, in our Discovery and Statistics Addons_ add additional src/main/resources/spring/spring-dspace-addon-discovery-services.xml_, do . Do the following:

Discovery (dspace/trunk/dspace-discovery/dspace-discovery-provider/src/main/resources/spring)

...

So in this tutorial, I've introduced you to The the ServiceManager, how to rethink your approach using Spring and not hardwire your application by binding its business logic to the parsing of a configuration file or other source of configuration, and how to lightly wire it together so that others can easily extend the implementation on their own. Likewise, I've show you the power of how to separate the configuration of the Script Launcher to a file that can be added to DSpace Maven Addon Module so that you can write your own commands without having to do anything at all in the dspace.cfg or launcher.xml in the DSpace config directory to enable them. A solution that will no doubt make your maintenence of those code changes much much easier as DSpace releases new versions and you need to merge yout config files to stay in line.  The final take home mantra for you to repeat 1000 times tonight before going to sleep... "If I don't have to alter configuration to add my changes into DSpace, I wouldn't need to merge differences when I upgrade."