On 18/05/2012 17:41, Clebert Suconic wrote:
> I really think those should be deprecated.. otherwise 10 years from
> now we are still stuck with these interfaces (that are really dated
> already).
>
> I'm not saying we remove them.. I'm just saying they should be deprecated.
Note that we are discussing the use of @Deprecated here. We can use whatever words we like (including the word
"deprecated") to discourage people from using them, and I intend to do that as much as possible. The restriction is on
the @Deprecated annotation because of the compiler warnings it causes.
Unfortunately I've been told the fact that many, many users still use the domain-specific API weakens the case for using
@Deprecated as it it would annoy many people :-(
>
> There are already things that have been deprecated on EE, such as BMP
> on EJBs, and I'm almost certain CMP 1.0.
Were these given the @Deprecated annotation?
The guidance I was given, and which is written down in
http://java.net/projects/javaee-spec/pages/CompatibilityRequirements
makes a distinction with "pruning" or "proposing for removal" an entire technology such as entity beans, and doing the
same for individual interfaces within an API.
> So, I don't think there's a general rule about not deprecating stuff.
> if there is we (as RedHat) are against it and we would like to raise
> an issue about it.
Noted. I'll follow this up.
Nigel
>
> On Fri, May 18, 2012 at 11:01 AM, Clebert Suconic
> <clebert.suconic_at_gmail.com> 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
>
>
>