Jaxrs-api: Clarify role of @PostConstruct annotated methods in validation steps

[ronsigal]

The first two validation steps are

• Phase 1 Inject field values and initialize bean properties as described in Section 3.2.
• Phase 2 Validate annotations on fields, property getters (if enabled) and the resource class. The order in which these validations are executed is implementation dependent.

In the case that CDI is enabled, RESTEasy currently initiates field/property validation at the end of InjectionTarget.inject(). However, since further initialization can take place in a @PostConstruct annotated method, field/property validation should be initiated from InjectionTarget.postConstruct().

It would be helpful if the role played by @PostConstruct methods were mentioned explicitly in the specification.

[mkarg]

@ronsigal You are a committer to JAX-RS. Feel free to provide a PR. May I assign this issue to you?

[ronsigal]

Ah, @mkarg, I didn't know I was a committer. ;-)

Sure, I'll certainly work on it.

[mkarg]

Ah, @mkarg, I didn't know I was a committer. ;-)

LOL

[chkal]

@ronsigal You are a committer to JAX-RS.

@mkarg Are you sure? Ron isn't listed in the GitHub team or on the Eclipse project page.

[mkarg]

@chkal Christian, you are right. May bad. I just checked the people in the Github assignee picker, and it does contain Ron. In fact it seems this picker contains all committers plus the reporter of the issue. Good to know that! Seems even after years I can learn something new about Github! ;-)

@ronsigal Sorry for the confusion. Christian is right. While I can assign the issue to you, you actually are not a committer yet. Anyways, you can become one by contributing frequently, so I still invite you to send a PR and I will be happy to review it! :-)

[ronsigal]

@mkarg, I'm crushed. ;-)

Right now I'm focused on a RESTEasy release, but I look forward to spending some time on JAX-RS issues.

[ronsigal]

Ummm, @mkarg, where does the specification document live?

[mkarg]

@ronsigal Due to legal issues Oracle was not able to transfer the specification document's source code to the Eclipse Foundation so far. You can find the latest pre-EF source here: https://github.com/jax-rs/spec.

[ronsigal]

Ahhhh, thanks. i guess, then, that we can't update https://github.com/jax-rs/spec. But I think this issue has to be addressed in the spec. Is there anything I can do now, or do we have to wait for an EF version of the spec document?

[ronsigal]

Wow, it's in TeX!! The other day when I suggested calling the Eclipse project JAK-RS, the K reminded me of the X in TeX. "TeX as in blecchhh", as Knuth said. ;-)

[mkarg]

@ronsigal Some PMC member told me that he expects by September we will have the spec transferred. So you can already prepare the changes, to have it at hand later.

[ronsigal]

Ah, ok. Thanks, @mkarg.

[ronsigal]

I've uploaded the spec document to https://www.papeeria.com, where it can be shared. In particular, if you want to see it, give me your email address and I can share it.

First, note that the javadoc for javax.annotation.PostConstruct says, "This annotation MUST be supported on all classes that support dependency injection." I believe that that applies to a Jakarta RESTful Web Services implementation even in the absence of CDI.

I've added text in four places:

1. The paragraph

If a method is correctly annotated with the javax.annotation.PostConstruct annotation (see the
PostConstruct javadoc for details), then that method must be executed after injections are done and
before the resource is put into use.

appears as the next to the last paragraph in section 3.2 "Fields and Bean Properties".

1. I inserted a clause in the first paragraph of section 4.1 "Lifecycle and Environment":

First the constructor (see Section 4.1.2) is called, then any requested dependencies are injected
(see Chapter 10), then a method correctly annotated with the javax.annotation.PostConstruct
annotation (see the PostConstruct javadoc for details), if such a method exists, is executed,
then the appropriate provider methods may be called multiple times (simultaneously), and finally >the object is made available for garbage collection.

1. I inserted a clause in the first paragraph of section 6.4 "Lifecycle":

First the constructor is called, then any requested dependencies are injected,
then a method correctly annotated with the javax.annotation.PostConstruct
annotation (see the PostConstruct javadoc for details), if such a method exists, is executed,
then the appropriate methods are called (simultaneously) as needed.

1. The paragraph

If a method is correctly annotated with the javax.annotation.PostConstruct
annotation (see the PostConstruct javadoc for details), then that method must be executed at
the end of Phase 1.

appears after Phases 1 through 4 in section 7.6 "Validation and Error Reporting".

[ronsigal]

I'm not sure if these changes are worth adding to the Change Log. I do suppose that it would be reasonable to add appropriate tests to the TCK.

[spericas]

@ronsigal Thanks for the contributions. I think it is fine to update the issue with the new text until the spec becomes available; changes like this do require a change log entry. Finally, I believe the intention is to convert all specs to AsciiDoc.

[ronsigal]

Thanks, @spericas.

[asoldano]

@ronsigal You are a committer to JAX-RS.

@mkarg Are you sure? Ron isn't listed in the GitHub team or on the Eclipse project page.

Btw, can you share a link to a page or such with the procedure for adding a committer? Ron should have actually been granted the committer role here for the same reason I was (not sure what didn't work in the process, possibly on our side); Ron is effectively leading RESTEasy with me these days and actually started contributing to it way before me... ;-)

[mkarg]

Btw, can you share a link to a page or such with the procedure for adding a committer? Ron should have actually been granted the committer role here for the same reason I was (not sure what didn't work in the process, possibly on our side); Ron is effectively leading RESTEasy with me these days and actually started contributing to it way before me... ;-)

You can find the rules in the Eclipse Project Handbook: https://www.eclipse.org/projects/handbook/#elections-committer.

[ronsigal]

Btw, @mkarg, I once got drunk with Bill Burke. If that doesn't qualify ... ;-)