Java – Annotation to Define Values for Method Argument

annotationsjavareflection

In a project, I have a task scheduling service, which is allowed to execute certain public methods from other services. Each service decides itself, which methods it want to make available for the task scheduling service by annotating them with @Operation. The task scheduling service simply will scan all given services for this annotation to get aware of methods it is allowed to be configured to execute. This means a user which wants to create a task will have a list of @Operation methods presented.

Let's take the example following example of an update service (one service among a few)

public interface UpdateService extends Service{

    @Operation
    public void update(String updateFileName);

    public List<String> getAvailableUpdateFileNames();

    @Operation
    public void ...

    ...
}

The way the UpdateService interface is declared, a user may create a task over the task service executing the update method. By letting the user freely configure a task with any string is mostly certain erroneous. The interface, in this case, therefore should present a list of predefined values, which can be used with the update method.

As it is, the update service also knows a getter method which reveals all available update. This would be ideal as a source for the predefined values.

That's why I came with the following approach:

public interface UpdateService extends Service{

    @Operation(sourceClass=UpdateService.class,sourceMethod="getAvailableUpdateFileNames")
    public void update(String updateFileName);

    public List<String> getAvailableUpdateFileNames();
}

The @Operation interface is introduced to a couple parameters.
The task service still scans all given service interfaces for @Operation annotations, to present a defined list to the user.

The Task manager also understands the arguments:

sourceClass: This class has to contain the source method
sourceMethod: This method returns values which can be used for the annotated interface function.

With the help of reflection, the task service executes the sourceMethod and will offer the returned values generically as predefined values for the task configuration of the update(String updateFileName) method in the user interface. The user can select such a value and schedule the update method with this selected value as an argument.

This example is very basic and currently would only work if the annotated method would have 1 argument. Although it would be completely generic and decoupled.

Is there a better way to solve this issue? Or isn't this approach that bad at all?

Best Answer

The design you presented has issues

You're using an annotation where an additional method of your Service interface should probably be used instead. Something like an execute() method that can call getAvailableUpdateFileNames and then invoke update. You're already implementing Service. Why design this complex reflection-based system to invoke update?
The workaround to the problem you've designed with a parameterized annotation is short-sighted. It may solve your immediate issues with UpdateService, but you'll likely encounter another service that you want to behave slightly differently (like having two parameters as you've acknowledged), and you've set a precedent for introducing annotation parameters to solve these problems.
Annotations, while fancy and widely-used, introduce several problems that affect your code's readability, maintainability, and testability. I would not use them when another design is clearly present.

If you want to separate the concerns of updating and the service that executes it, I suggest collaboration.

Where UpdateService.execute is implemented like:

List<String> fileNames = updater.getAvailableFileNames();
updater.update(fileNames.get(0));

This design has the benefit that it can execute any method on any object instead of just those with a single parameter. The concerns are separated, and each piece can be unit-tested independently.

Don't use a Java Bean if you can

While Java Beans are extremely useful on many occasions, I would argue that it would be better for User not to be a bean in the context you describe. You can design this class so that its instances are always in a valid state.

In the following example, name is mandatory and address is optional.

class User {
    private String name;
    private String address;

    User(String name) {
        setName(name);
    }

    void setName(String name) {
        if (name == null)
            throw new IllegalArgumentException("[name] cannot be null");
        this.name = name;
    }
    String getName() {
        return name;
    }

    void setAddress(String address) {
        this.address = address;
    }
    String getAddress() {
        return address;
    }
}

As you can see, with that design, it is not possible at any point to have a User instance without a name. However, you can have instances with an address, as well as instances without one.

Also notice that in the code example above I am performing some basic validation. If needed, you can perform more complex validation than that. For example by making sure the name does not contain characters not likely to appear in your context.

Things to consider

There are a few things to consider to make sure such a class meets its goal. Only its immutable content can be shown to the outside world, for example. Consider another similar class that contains a list that must always contain at least one item. If that list is mutable and external code can access it (through a getter, for example), nothing stops it from removing objects from it until it is empty, putting your initial instance in a state that shouldn't be allowed. Of course, if you need to expose that data, consider only giving a copy of the list or have it immutable.

What if there are a lot of mandatory values ?

If it makes sense to group some of these values in classes of their own, and that in doing so the constructor becomes wieldable, go for it. Such classes should be designed with the aforementioned constraints in mind.

Alternatively, you can define a Builder to help in constructing the objects.

What if a Java Bean is needed in a specific part of my code?

That design may work well in most places these classes are used except at specific places where, because for example a framework needs it, you must use Java beans. When that happens, instead of using beans everywhere, you can define a bean that contains the same data with added constructor and method to take care of data conversion. For example...

class UserBean {
    private String name;
    private String address;

    UserBean() {
    }
    UserBean(User user) {
        this.name = user.getName();
        this.address = user.getAddress();
    }

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

    void setAddress(String address) {
        this.address = address;
    }
    String getAddress() {
        return address;
    }

    User toUser() {
        User ret = new User(name);
        ret.setAddress(address);
        return ret;
    }
}

That way it is easy to have a bean from the non-bean instance and vice-versa.

Conclusion

As you can see the problem you have can be solved while keeping its initial signature. It is possible that going this way results in more code to be written for a similar result (though I wouldn't vouch for it, since passing a necessarily valid object around means less validation needed by the code using it).

I have tried to keep it short (ahem...) and to use here a design close to your initial one (beans). However, it is more for the sake of the explanation rather than because I consider that the best design. With all the hassle of maybe needing builders and additional bean classes, I would tend to go the extra mile and make the class being passed around immutable. That is how I have designed a recent, short project and it turned out to work particularly well.

Best Answer

Related Solutions

Varargs vs Lists – Which to Use in Java Constructors and Methods

Java – Service method, bean as an argument and mandatory attributes

Don't use a Java Bean if you can

Things to consider

What if there are a lot of mandatory values ?

What if a Java Bean is needed in a specific part of my code?

Conclusion

Related Topic