You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jclouds.apache.org by Jeremy Daggett <no...@github.com> on 2013/12/16 21:20:21 UTC

[jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

This PR provides the necessary deprecation warnings to the legacy Swift API. Since the new code is in the jclouds-labs-openstack project, the necessary links to the new APIs have also been provided as reference.
You can merge this Pull Request by running:

  git pull https://github.com/rackspace/jclouds javadoc-updates

Or you can view, comment on it, or merge it online at:

  https://github.com/jclouds/jclouds/pull/237

-- Commit Summary --

  * Add deprecation warnings and provide links to new APIs

-- File Changes --

    M apis/swift/src/main/java/org/jclouds/openstack/swift/CommonSwiftAsyncClient.java (6)
    M apis/swift/src/main/java/org/jclouds/openstack/swift/CommonSwiftClient.java (112)
    M apis/swift/src/main/java/org/jclouds/openstack/swift/SwiftAsyncClient.java (3)
    M apis/swift/src/main/java/org/jclouds/openstack/swift/SwiftClient.java (3)
    M apis/swift/src/main/java/org/jclouds/openstack/swift/SwiftKeystoneAsyncClient.java (2)
    M apis/swift/src/main/java/org/jclouds/openstack/swift/SwiftKeystoneClient.java (3)

-- Patch Links --

https://github.com/jclouds/jclouds/pull/237.patch
https://github.com/jclouds/jclouds/pull/237.diff

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
Merged to master and 1.7.x

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39514924

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> jclouds-pull-requests #729 UNSTABLE

Unrelated [test failure](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/org.apache.jclouds$jclouds-compute/729/testReport/junit/org.jclouds.compute.util/ConcurrentOpenSocketFinderTest/testChecksSocketsConcurrently/), by the way

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39381313

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1193](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1193/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39244368

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
Okay. We'll hold off on this one. 

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30704126

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> My take: deprecate early, rather than late, even if replacement functionality is not already there. I realize not 
> everybody would agree with me.

Or, as a halfway house, add a Javadoc warning that this code will soon be deprecated and then removed? Won't create a compiler deprecation warning (which seems a little harsh, since users can't avoid that without replacement functionality), but at least gives them a heads-up?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30720607

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Jeremy Daggett <no...@github.com>.
@demobox Yes, the plan was that the current API (apis/swift) will go away. It will be replaced with the jclouds-labs-openstack/openstack-swift API, which will have feature parity.  I agree with you and @zack-shoylev that having the JavaDoc deprecation would be a great for warning for users, and, as you say, the deprecation annotation on the class could be removed so there are no compiler warnings. Can we just close this PR for now? I can submit the changes in another PR. WDYT?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30765577

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
@ntolia By definition a HP custom TempURL implementation wouldn't belong in any Swift API. It should be in the HP provider. I've contacted someone at HP to see if they'll be able to dedicate someone to jclouds. It sounds like they are and hopefully we'll know more next week.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39514535

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #727](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/727/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39278971

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Zack Shoylev <no...@github.com>.
My take: deprecate early, rather than late, even if replacement functionality is not already there. I realize not everybody would agree with me.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30712038

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #730](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/730/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39388268

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
+1

Doc/Annotation change only but still waiting on builds. Then I'll merge it.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30700594

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Bayer <no...@github.com>.
+1 to what @andrewgaul said - unless/until the new code has the ability to completely replace the existing stuff...

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30701669

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> Deprecated means: You should not use it.

Personally, I think of "deprecated" as "you need to think about moving away from this at some point". Hopefully, the deprecation message gives more details about _when_ that needs to happen. But I generally do not immediately try to move away from all deprecated calls unless the deprecation warning strongly advises me to do so (e.g. the call is unsafe, or something like that).

Of course, I agree that we should generally not **remove** any deprecated methods before the functionality is available elsewhere.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39656201

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Gaul <no...@github.com>.
Shouldn't we bring up the labs code to feature-parity with the core code before deprecating it?  Notably we do not have provider facades for the labs code.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30701304

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1198](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1198/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39279900

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Niraj Tolia <no...@github.com>.
@jdaggett Do the new Swift APIs have support for HPCS's custom TempURL implementation? If not, would it be possible to get to feature parity before starting to deprecate old functionality?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39283010

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
Closed #237.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #479](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/479/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30701014

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Fabian Lange <no...@github.com>.
I am not worried :) I am confused. In fact I plan to have a production version of our software talking to os ceph via jclouds swift. But I don't know which API to use. The deprecated one, or the beta one. I usually expect to find a clear answer in code. and after beta and deprecation annotations, this is not the case. Maybe a note on the jclouds-openstack lab readme could help, which says which API is recommended atm. You might have seen that I opened to jira on bugs in swift api (deprecated). maybe I should use the labs one?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39468405

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> jclouds-pull-requests #726 UNSTABLE

Still the same [Checkstyle violation](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/726/org.apache.jclouds.api$swift/violations/)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39278563

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
I did better Beta documentation in https://github.com/jclouds/jclouds-labs-openstack/pull/93

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39514233

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> Can we please get this merged and backported into the 1.7.x branch?

Do you want to squash this down first, or do we want two commits here?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39381258

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Jeremy Daggett <no...@github.com>.
@everett-toews Let me take a look at this today so we can get it into 1.7.2!

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39235441

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Fabian Lange <no...@github.com>.
As a user of the current org.jclouds.openstack.swift.SwiftClient, I am heavily confused by the change.
The labs.v1.SwiftApi is marked "@Beta".
Deprecated means: You should not use it.
Beta means: You should not use it.

Deprecating a "stable" API without having a "stable" replacement is a no go for me.
Either the old one is not really deprecated, or the new one is not really beta.

>From my user point of view you should not deprecate it in 1.7.x. 

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39420529

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Zack Shoylev <no...@github.com>.
Updating javadocs seems like the way to go. Good suggestion, @demobox

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30769735

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #723](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/723/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39243332

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
Reworking this PR is probably easier.

@andrewgaul @abayer You two okay with this plan.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30767663

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Jeremy Daggett <no...@github.com>.
@CodingFabian Not to worry, Guava uses this all over the place to indicate that an API is subject to change. Refer to the last paragraph "Important Warnings" [here](https://code.google.com/p/guava-libraries/).

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39446518

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
> jclouds-pull-requests #728 SUCCESS

Checkstyle is also [clean](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/728/)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39293399

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by BuildHive <no...@github.com>.
[jclouds » jclouds #987](https://buildhive.cloudbees.com/job/jclouds/job/jclouds/987/) UNSTABLE
Looks like there's a problem with this pull request
[(what's this?)](https://www.cloudbees.com/what-is-buildhive)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39282942

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
>  I can submit the changes in another PR. WDYT?

Works for me. Or rework this PR - whatever you prefer ;-)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30766557

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1200](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1200/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39388942

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by BuildHive <no...@github.com>.
[jclouds » jclouds #988](https://buildhive.cloudbees.com/job/jclouds/job/jclouds/988/) SUCCESS
This pull request looks good
[(what's this?)](https://www.cloudbees.com/what-is-buildhive)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39285319

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1197](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1197/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39279088

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #728](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/728/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39279405

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
@CodingFabian We're well aware that the old SwiftClient has been around for a long time and is heavily used. I also understand it's a bit confusing. I think the source of the confusion is that we're being very cautious (overly cautious?) about this transition.

We're playing it cautious by using the @Beta annotations on the new apis/providers in labs. These are new apis/providers to jclouds and hence are deserving of the label Beta. We want people to use it and give us feedback. We may change the interfaces based on that feedback but I don't see them being major changes.

You're right. We do need to communicate that better. We need better comments on the @Beta annotations and a mention in the labs README. There are some PRs that need to be merged before we can make some of these updates though.

We do recommend using the beta one. In the long run there will be less work for you by adopting the beta API now rather than having to switch over to it later.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39471184

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #942](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/942/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30701000

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1199](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1199/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39358546

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
@jdaggett: Is the underlying Swift API going to go away? In that case, I guess it wouldn't be bad to warn users of that in advance, independently of whether we have the jclouds replacement in place..?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30704470

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Jeremy Daggett <no...@github.com>.
I discovered that when you organize imports (command-O) in Eclipse, if you reference a class by name in the JavaDocs it adds the import. I will make sure to run Checkstyle in Eclipse before submitting PRs in the future.  

@demobox Can we please get this merged and backported into the 1.7.x branch? 

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39356439

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by BuildHive <no...@github.com>.
[jclouds » jclouds #990](https://buildhive.cloudbees.com/job/jclouds/job/jclouds/990/) SUCCESS
This pull request looks good
[(what's this?)](https://www.cloudbees.com/what-is-buildhive)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39359307

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Jeremy Daggett <no...@github.com>.
I am going to make all references state "...will be removed in jclouds 1.8". Any objections @andrewgaul @everett-toews ?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39243863

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Phillips <no...@github.com>.
[minor] I might use "replaced by" instead of "replaced with", but fine as-is. Squash'n'rebase still to come, I guess?

Looks good to me, but I think @everett-toews or @zack-shoylev will be better judges here.

One [Checkstyle warning](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1193/org.apache.jclouds.api$swift/violations/file/src/main/java/org/jclouds/openstack/swift/CommonSwiftClient.java/) about an unneeded import, by the way.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39274539

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by BuildHive <no...@github.com>.
[jclouds » jclouds #982](https://buildhive.cloudbees.com/job/jclouds/job/jclouds/982/) SUCCESS
This pull request looks good
[(what's this?)](https://www.cloudbees.com/what-is-buildhive)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39241979

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #726](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/726/) UNSTABLE
Looks like there's a problem with this pull request

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39277812

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Everett Toews <no...@github.com>.
@jdaggett Does this need to be updated prior to the 1.7.2 release? We should really get this into 1.7.2.

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39219519

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-java-7-pull-requests #1196](https://jclouds.ci.cloudbees.com/job/jclouds-java-7-pull-requests/1196/) SUCCESS
This pull request looks good

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39278216

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by CloudBees pull request builder plugin <no...@github.com>.
[jclouds-pull-requests #729](https://jclouds.ci.cloudbees.com/job/jclouds-pull-requests/729/) UNSTABLE
Looks like there's a problem with this pull request

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39358086

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Andrew Gaul <no...@github.com>.
We have talked about the new Swift API for some years and as of today it does not meet my and likely others needs.  Given its slow evolution I do not have confidence that it will replace the old API in the next major release.  Instead of arguing about deprecation, perhaps we should *improve* the code so that such deprecation decisions will be obvious?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-30770093

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by BuildHive <no...@github.com>.
[jclouds » jclouds #991](https://buildhive.cloudbees.com/job/jclouds/job/jclouds/991/) SUCCESS
This pull request looks good
[(what's this?)](https://www.cloudbees.com/what-is-buildhive)

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39387447

Re: [jclouds] Add deprecation warnings and provide links to new Swift APIs (#237)

Posted by Shri Javadekar <no...@github.com>.
Do we know what's missing in the new implementation (in jclouds-labs-openstack) that is present in the old implementation? In other words, what's the effort required to have feature parity between the new implementation and the old one?

---
Reply to this email directly or view it on GitHub:
https://github.com/jclouds/jclouds/pull/237#issuecomment-39243860