If it makes anyone feel better, I constantly curse at my computer screen
when it warns me about sun.misc.Base64Encoder.
Either way, I'm ok with this being a javadoc only change. Perhaps
implementors should be encouraged to add log messages if the developer is
using a domain specific interface?
On Fri, May 18, 2012 at 12:40 PM, Rüdiger zu Dohna
<ruediger.dohna_at_1und1.de>wrote:
> +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
>
>