I'm sort of on the fence about this and am not sure there is a right/wrong
answer. I do think @Deprecate is good because it makes it salient what older
APIs should be ported over. On the other hand, I suppose it can be annoying
for folks unwilling/unable to port.
> -----Original Message-----
> From: Nigel Deakin [mailto:nigel.deakin_at_oracle.com]
> Sent: Friday, May 18, 2012 11:22 AM
> To: jsr343-experts_at_jms-spec.java.net
> Subject: [jsr343-experts] Re: (JMS_SPEC-47) Deprecate domain-specific APIs
and
> propose for removal
>
> On 18/05/2012 15:58, Clebert Suconic wrote:
> > That doesn't make much sense to me...
> >
> > @Deprecate won't certainly break compatibility.
> >
> > The rule/requirement about not deprecating seems a bit arbitrary to
> > me. Isn't that a rule that could be changed?
>
> The requirement about not deprecating was based on a view that @Deprecated
> was simply too "noisy" and annoying. I was told that when it had been used
for
> some interfaces in the Java SE API it had proved unpopular.
>
> If this EG would like me to go back (to the Java EE spec leads) and
challenge this
> instruction I will.
>
> However I think we need to reword the javadocs and spec much as I suggest
in
> any case.
>
> Nigel
>
>
> >
> > On Fri, May 18, 2012 at 9:38 AM, Nigel Deakin<nigel.deakin_at_oracle.com>
> wrote:
> >> Here's another old JIRA issue that I'm trying to make progress with:
> >> http://java.net/jira/browse/JMS_SPEC-47
> >>
> >> You may remember we discussed this back in September 2011. This
> >> relates to the domain-specific interfaces QueueConnectionFactory,
> >> QueueConnection, QueueSession, QueueSender and QueueReceiver,
> >> TopicConnectionFactory, TopicConnection, TopicSession, TopicPublisher
> >> and TopicSubscriber (and the optional XAQueueConnectionFactory,
> >> XATopicConnectionFactory, XAQueueConnection, XATopicConnection,
> XAQueueSession and XATopicSession).
> >>
> >> We agreed (with support from Reza, Ruediger and Clebert) with my
> >> proposal
> >> that:
> >>
> >>
> >> * These interfaces would be formally marked as deprecated, by use of
> >> the @java.lang.Deprecated annotation. This would cause compilers to
> >> issue a warning when a deprecated method was used.
> >>
> >> * These interfaces would be formally marked in the specification as
> >> being "proposed for removal", with the expectation that they would be
> >> made optional in the next release.
> >>
> >> However you may also remember that some time after that I checked
> >> with the Java EE spec leads and other colleagues and was told that
> >> doing this would break the compatibility requirements for Java EE
> >> specifications. I asked questions to determine what these were, wrote
> >> them down, and the Java EE spec leads have published them here:
> >> http://java.net/projects/javaee-spec/pages/CompatibilityRequirements
> >>
> >> In short, these requirements mean that we cannot mark any existing
> >> interfaces as @java.lang.Deprecated, and we cannot propose the
> >> removal of individual interfaces for removal in the future.
> >> Essentially, we're stuck with these interfaces indefinitely. Although
> >> there might be scope to deprecate or interfaces which are unsafe in
> >> some way, or propose interfaces for removal that we know very few
people
> actually use, neither applies here.
> >>
> >> This means that we cannot implement my original proposal.
> >>
> >> However we are still free to write whatever we like in the spec and
> >> javadocs to discourage users from using these interfaces and
> >> encouraging them to use the unified API instead.
> >>
> >> I propose we describe these interfaces as "obsolete" and modify the
> >> spec and javadocs to make it clear that the domain-specific
> >> interfaces are a legacy from JMS 1.0 which is kept only to preserve
> >> compatibility, and to encourage applications to use the
domain-independent
> interfaces instead.
> >>
> >> Here are some of the places that need to be changed:
> >>
> >> 1. Modify the package description
> >> http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/javax/jms/package-summa
> >> ry.html#package_description and change the section "JMS Interfaces"
> >> to give clear precedence to the domain-independent interfaces and to
> >> state clearly that the domain-specific interfaces are a legacy from
> >> JMS 1.0 which is kept only to preserve compatibility.
> >>
> >> 2. Reword section 1.2.3.3 "JMS domains", 2.4 "Two messaging styles",
> >> 2.5 "JMS interfaces", 5.1. "Overview" (of PTP), 6.1 "Overview" (of
> >> pub/sub), 8.6 "JMS application server interfaces" to give clear
> >> precedence to the domain-independent interfaces and to state clearly
> >> that the domain-specific interfaces are a legacy from JMS 1.0 which
> >> is kept only to preserve compatibility.
> >>
> >> 3. Insert additional text into the class comment for
> >> QueueConnectionFactory, QueueConnection, QueueSession, QueueSender
> >> and QueueReceiver, TopicConnectionFactory, TopicConnection,
> >> TopicSession, TopicPublisher and TopicSubscriber,
> >> XAQueueConnectionFactory, XATopicConnectionFactory,
> >> XAQueueConnection, XATopicConnection, XAQueueSession and
> >> XATopicSession along the lines of
> >>
> >> "This interface is part of the JMS domain-specific API and is now
obsolete.
> >> Applications are encouraged to use the JMS domain-independent API
instead.
> >> The domain-independent equivalent to this interface is foo. For more
> >> information see bar.
> >>
> >> 4. Insert a similar comment into the method comment for the two
> >> createDurableSubscriber methods on Session.
> >>
> >> I will make the changes that I think are needed and offer them to
> >> this group for review.
> >>
> >> I know this isn't what we wanted, but this is the best I think we can
do...
> >>
> >> Nigel
> >>
> >
> >
> >