Moving utility classes to internal namespace

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Moving utility classes to internal namespace

Alexei Barantsev
Hi, devs,

I've performed a kind of controversial change in Java binding and I want to explain the reasons:
I've moved all IO, OS and Net utility classes to internal namespace (org.openqa.selenium.internal package).

Despite the fact that these utility classes can be used in clients' code, they don't form Selenium external API. They are part of internal API. They are not indended for use by clients.

Selenium is dedicated browser automation API, and I want this API to be as clean as possible. In no means classes like CircularOutputStream or PortProber or ExecutableFinder should be considered a part of browser automation API.

I understand that my commits may break clients' code. But I think it is a revitalizing crysis.

If you think that some of the moved classes should be considered the official Selenium external API -- let's discuss it, agree on it, and I'll move them back.

If you think that some of the moved classes should be temporary (for a release or two) kept in the old location -- let's discuss it, agree on it, and I'll create shims and mark them deprecated.

Regards,
-- 
Alexei Barantsev
Software-Testing.Ru
Selenium2.Ru

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/f4daa78b-9b12-4813-857b-0bad4ae023b0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Moving utility classes to internal namespace

Krishnan Mahadevan
Alexei,

Would it be possible for you to consider providing these IO, OS and Net utility classes as a separate utility package that can be used by downstream clients instead of moving them into an internal package ? 

I know the intent of these classes were to serve the internal purpose of Selenium and not meant to be used by downstream users. 

But considering the value add of some of these classes, and to save the hassle of a selenium user having to re-invent the wheel, I was wondering if it would be too much to ask, if these classes can be provided as official "non-browser support classes" provided as a by-product of what Selenium exposes viz., API for browser automation ?

PS: I am not part of the Selenium dev, but just another selenium enthusiast expressing my opinion.

Thanks & Regards
Krishnan Mahadevan

"All the desirable things in life are either illegal, expensive, fattening or in love with someone else!"
My Scribblings @ http://wakened-cognition.blogspot.com/
My Technical Scribbings @ http://rationaleemotions.wordpress.com/

On Thu, Jan 5, 2017 at 1:48 PM, Alexei Barantsev <[hidden email]> wrote:
Hi, devs,

I've performed a kind of controversial change in Java binding and I want to explain the reasons:
I've moved all IO, OS and Net utility classes to internal namespace (org.openqa.selenium.internal package).

Despite the fact that these utility classes can be used in clients' code, they don't form Selenium external API. They are part of internal API. They are not indended for use by clients.

Selenium is dedicated browser automation API, and I want this API to be as clean as possible. In no means classes like CircularOutputStream or PortProber or ExecutableFinder should be considered a part of browser automation API.

I understand that my commits may break clients' code. But I think it is a revitalizing crysis.

If you think that some of the moved classes should be considered the official Selenium external API -- let's discuss it, agree on it, and I'll move them back.

If you think that some of the moved classes should be temporary (for a release or two) kept in the old location -- let's discuss it, agree on it, and I'll create shims and mark them deprecated.

Regards,
-- 
Alexei Barantsev
Software-Testing.Ru
Selenium2.Ru

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/f4daa78b-9b12-4813-857b-0bad4ae023b0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/CANikZL%3Duhmw8JR%2Bce0asbGsy33mVFfLm31N5z-eKypge76JRig%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Moving utility classes to internal namespace

David Burns
In reply to this post by Alexei Barantsev
Do we have a sense for how this might break people?

I am all for making internal APIs obvious as internal only but since people might have used this because our mistake. Were they deprecated first?

David


On Thu, Jan 5, 2017 at 8:18 AM, Alexei Barantsev <[hidden email]> wrote:
Hi, devs,

I've performed a kind of controversial change in Java binding and I want to explain the reasons:
I've moved all IO, OS and Net utility classes to internal namespace (org.openqa.selenium.internal package).

Despite the fact that these utility classes can be used in clients' code, they don't form Selenium external API. They are part of internal API. They are not indended for use by clients.

Selenium is dedicated browser automation API, and I want this API to be as clean as possible. In no means classes like CircularOutputStream or PortProber or ExecutableFinder should be considered a part of browser automation API.

I understand that my commits may break clients' code. But I think it is a revitalizing crysis.

If you think that some of the moved classes should be considered the official Selenium external API -- let's discuss it, agree on it, and I'll move them back.

If you think that some of the moved classes should be temporary (for a release or two) kept in the old location -- let's discuss it, agree on it, and I'll create shims and mark them deprecated.

Regards,
-- 
Alexei Barantsev
Software-Testing.Ru
Selenium2.Ru

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/f4daa78b-9b12-4813-857b-0bad4ae023b0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/CAPmg_ctwQ7cg-xV-7PJMVZ1Czw%3Dm24%3DGYpX3NWediXRtv2uNAQ%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Moving utility classes to internal namespace

Simon Stewart
In reply to this post by Alexei Barantsev
Hi,

After chatting with Alexei on IRC, I rolled these changes back. I agree with the idea in principle, but there are a few things to bear in mind.

First of all, I think it's worth bearing in mind that we're entirely sure who's depending on these classes. The very least we should do is follow our own deprecation process by marking the classes deprecated and providing alternatives that people can switch to --- if the class is in a package marked "internal", then I consider that fair warning.

Secondly, lots of the classes form a useful substrate on which to build selenium implementations. I'm thinking of things like CommandLine, PortProber, and UrlChecker that are amazingly useful utility classes. On several occasions, both Luke and I have lamented the lack of these being easily available as their own library. We could probably tighten visibility of some classes/interfaces (or move them to "{io,net,os}/internal") and release them as their own library on maven (*support-library"? I hate the name "util" :)

Thirdly, and finally, perhaps we need a "@Internal" annotation for classes that we want to keep internal, and treat like @Beta, but with additional stability.

Thoughts?

Simon

On Thu, Jan 5, 2017 at 8:18 AM, Alexei Barantsev <[hidden email]> wrote:
Hi, devs,

I've performed a kind of controversial change in Java binding and I want to explain the reasons:
I've moved all IO, OS and Net utility classes to internal namespace (org.openqa.selenium.internal package).

Despite the fact that these utility classes can be used in clients' code, they don't form Selenium external API. They are part of internal API. They are not indended for use by clients.

Selenium is dedicated browser automation API, and I want this API to be as clean as possible. In no means classes like CircularOutputStream or PortProber or ExecutableFinder should be considered a part of browser automation API.

I understand that my commits may break clients' code. But I think it is a revitalizing crysis.

If you think that some of the moved classes should be considered the official Selenium external API -- let's discuss it, agree on it, and I'll move them back.

If you think that some of the moved classes should be temporary (for a release or two) kept in the old location -- let's discuss it, agree on it, and I'll create shims and mark them deprecated.

Regards,
-- 
Alexei Barantsev
Software-Testing.Ru
Selenium2.Ru

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/f4daa78b-9b12-4813-857b-0bad4ae023b0%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Selenium Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [hidden email].
To view this discussion on the web visit https://groups.google.com/d/msgid/selenium-developers/CAOrAhYGjbGzYGxhW54GYGv8i7YgFEp-pWxyV%3DSJBVeSEztaqqA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Loading...