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-summary.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
>>
>
>
>