Rename @PropertyNames to @FactoryProperties

[drekbour]

@PropertyNames is specific to factory-method builders. I strongly favour @FactoryProperties, in keeping with @ConstructorProperties (principle of least surprise).

• Deprecate @PropertyNames.
• Add @FactoryProperties which is identical, ensure code base treats them identically with absolute minimum of duplicate reference (can probably get this down to a single utility method)
• Compilation should fail if both @PropertyNames and @FactoryProperties are present
• Refactor tests to use @FactoryProperties
• Refactor samples to use @FactoryProperties
• Add minimal test for deprecated @PropertyNames
• Update documentation to use @FactoryProperties

Marc

[mkarneim]

Actually I also have thought about @PropertyNames and @ConstructorProperties. I didn't like it that two annotations are used for the same thing.

My solution looks different to yours - but perhaps you agree with me?

I would remove the use of the @ConstructorProperties annotation completely and instead only support @PropertyNames for both locations (Constructor & Factory Method). For the sake of backward compatability we could support the @ConstructorProperties annotation for a short while.

I would prefer this instead of having two different annotations since both annotations just mean the same. One annotation is sufficient.
Further, the @ConstructorProperties annotation is borrowed from package "java.beans" and not part of PB. I feel it is better to have all annotations in our control.

Comments?

[mkarneim]

Just another thought:

The adjustment of @ParameterNames is unwieldy and error-prone when parameter positions are changed during a refactoring. Having a by-parameter annotation (like @QueryParam) would solve this.

We could go into that direction...

[drekbour]

@ConstructorProperties is used for precisely what PB requires. If a class has (or needs) it, PB must follow the mappings given by @ConstructorProperties. I don't see how you could replace it, end-users would end up with a constructor that has both a PB-specific and @cp annotations which would be truly horrible.

@PropertyNames applies the same contract to factory methods which makes sense. @FactoryProperties simply brings the name (and hence, expectation of usage) in line.

I too noticed that Paranamer supports JSR-330 @nAmed and that many other frameworks (esp. marshallers like Jackson and rails/struts type web app ones) also have their own per-parameter annotations.

public void doSomething(@Named("usedName") String ignoredName)

I think there is merit in the idea but it's another feature entirely to this one so will cease on this point.

[mkarneim]

I am still not convinced that staying with @ConstructorProperties is the right decision.

Mostly is has to do with the fact that I find it really handy to have an annotation on a per-param basis.
For example, when doing a method signature refactoring with Eclipse, say reordering the parameters, this is really neat since the annotations stay with their parameters, while the @ConstructorProperties annotation just becomes incorrect, possibly unnoticed.

But I also see your point. Perhaps if we implemented the "implicit naming" feature (issue #42), then we possibly could expect that the need for annotating the parameters decreases anyway.

Hmm...

[mkarneim]

Well, let's go for it.

(PS: I think I could introduce another parameter-based annotation later)