Add possibility to deprecate API

[koperm]

As the created API changes in a lifetime, I would like to be able to @Deprecate accessor methods. This PR gives that opportunity.

Example:

@DeprecatedApi("@deprecated Use {@link #getPrePaddingTimeRef} instead")
private final long prePaddingTime;

Model annotated field transformed into:

/**
* @deprecated Use {@link #getPrePaddingTimeRef} instead.
*/
@Deprecated
public long getPrePaddingTime() {
    return delegate().getPrePaddingTime(ordinal);
}

[ghost]

@koperm I like the intent of this PR. We'd like some time to review internally before committing to this API

[koperm]

@toolbear thanks for your insight and reply. I updated the code according to the tips and look forward to hearing from you.

[koperm]

I added JavaDoc and replied to @PaulSandoz comments. Give some feedback, please.

[koperm]

@PaulSandoz, @toolbear any chance to move on with this PR?

[PaulSandoz]

@koperm sorry for the delay, been busy with other things. The JavaDoc looks good but overall the implementation is still too specific to deprecation.

Another use-case we recently thought about was declaring a field to be non-null. At the validation stage a validator could check if a null-value was assigned. This adds another aspect to any such design in that we don't want to add a dependency in hollow to an external library but we don't necessarily want to define our own annotation that's different to what developers ordinarily use, which means considering an abstraction to map a third party annotation to the associated hollow schema field artifact.

So IMHO this requires more thought and work to get this right. How about we work together under a feature branch in the hollow repo?

[koperm]

@PaulSandoz @Deprected annotation has a flaw because doesn't allow for any comment/message. That's why @DeprecatedApi was introduced, but the in general approach any already existed annotation could be used, including the Java's @Deprecated.

As you mentioned a third-party dependencies problem arises in the generic approach. In the case of third-party annotations, import statement needs to be taken into consideration. The second thing is the validation of created java files from the model: AFAIK the validation involves the compilation of the files. This is still a valid approach in case of third-party annotations?

These and probably many more problems should be overcome to accomplish generic approach.

I admit that this simplified feature would be very useful to me but in the long run generic way could give much more. Feel free to do whatever you consider right, just give me some notification. I would be glad to help.

[PaulSandoz]

@koperm re: @deprecatedapi we are in strong agreement :-)

Next week i will create a pull request merging in your deprecated feature with a more general mechanism for "modifiers" on fields and notify you for review and feedback.