+1 on just marking it obsolete... I don't think it's necessary to challenge that rule, as it's most often useful.
On 2012-05-18, at 18:01, Clebert Suconic wrote:
> 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