On Fri, May 18, 2012 at 10:54 AM, Reza Rahman <reza_rahman_at_lycos.com> wrote:
> 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.
They can always disable warn deprecate on that case. They are just
being informed that this is deprecated.
I see a lot of users still developing *new* code with Topic* and
Queue* just for the lack of knowledge.
>
>> -----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
>> >>
>> >
>> >
>> >
>
--
Clebert Suconic
http://community.jboss.org/people/clebert.suconic@jboss.com
http://clebertsuconic.blogspot.com