pojomatic-users

[Pojomatic-users] Pojomatic API decisions

[Chris H. <han...@gm...>]

I was (re)watching Bloch on API design the other day (
http://www.infoq.com/presentations/effective-api-design ) and I had a couple
of takeaways which apply to Pojomatic. We need to discuss/address these
before it's too late, meaning before 1.0.

1) Provide programmatic access to all data available in string form.  Among
other things, this prevents users from parsing the string output.
1a) We can, and I think should, refactor the Differences API for
programmatic access. We could take a page out of the Google Collections book
on this one:
http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapDifference.html

I will work on this one.

2) Design for extensibility. If you have a successful API, the users will
want to do more with it. Even if you get the API right the first time, you
won't get it complete the first time.
2a) One way to do this would be to implement extension separately from the
existing hashCode(), equals(Object), and toString() functionality. That
would be a small API change which could be done as a point release after
1.0, but then existing functionality would be inconsistent with the
extensible API and might even become a candidate for deprecation at that
point.
2b) Another way to go would be to create the extensible API and refactor the
existing functionality to use that API right away. This is worse in the
short term because it delays 1.0, but might pay off in the long term.

To me, the question is not if we should create an extensible API, but when.
What do you think?

Thanks,
-Chris

Re: [Pojomatic-users] Pojomatic API decisions

[Ian R. <ian...@gm...>]

Agreed on the Differences API.  Do you think we would have to make backwards
incompatible changes to expose details?  If not, this can be

On Thu, Feb 25, 2010 at 12:02 AM, Chris Hansen <han...@gm...>wrote:

> I was (re)watching Bloch on API design the other day (
> http://www.infoq.com/presentations/effective-api-design ) and I had a
> couple of takeaways which apply to Pojomatic. We need to discuss/address
> these before it's too late, meaning before 1.0.
>
> 1) Provide programmatic access to all data available in string form.  Among
> other things, this prevents users from parsing the string output.
> 1a) We can, and I think should, refactor the Differences API for
> programmatic access. We could take a page out of the Google Collections book
> on this one:
> http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapDifference.html
>
> I will work on this one.
>
> 2) Design for extensibility. If you have a successful API, the users will
> want to do more with it. Even if you get the API right the first time, you
> won't get it complete the first time.
> 2a) One way to do this would be to implement extension separately from the
> existing hashCode(), equals(Object), and toString() functionality. That
> would be a small API change which could be done as a point release after
> 1.0, but then existing functionality would be inconsistent with the
> extensible API and might even become a candidate for deprecation at that
> point.
> 2b) Another way to go would be to create the extensible API and refactor
> the existing functionality to use that API right away. This is worse in the
> short term because it delays 1.0, but might pay off in the long term.
>
> To me, the question is not if we should create an extensible API, but when.
> What do you think?
>
> Thanks,
> -Chris
>
>
> ------------------------------------------------------------------------------
> Download Intel&#174; Parallel Studio Eval
> Try the new software tools for yourself. Speed compiling, find bugs
> proactively, and fine-tune applications for parallel performance.
> See why Intel Parallel Studio got high marks during beta.
> http://p.sf.net/sfu/intel-sw-dev
> _______________________________________________
> Pojomatic-users mailing list
> Poj...@li...
> https://lists.sourceforge.net/lists/listinfo/pojomatic-users
>
>

Re: [Pojomatic-users] Pojomatic API decisions

[Ian R. <ian...@gm...>]

Agreed on the Differences API.  Do you think we would have to make backwards
incompatible changes to expose details?  If not, this can be a post 1.0
task.

On the extensibility front, I question the value.  Here's what I can see
pojomatic offering to those who might wish to extend the API to support
additional functions beyond equals, hashCode, toString and differences:

   - Creating a unique pojomator per class (SelfPopulatingMap).
   - As part of creating the pojomator, determine which properties are
   assigned to which roles.

That doesn't really feel like a lot.  On the flip side, in order to support
additional functions, we would need to completely revamp the annotation
strategy; IMHO, this would only be worthwhile if we could do so without
requiring greater verbosity.

A separate direction to extend the API would be supporting custom equals
strategies; I could see a desire to do alternate handling of collection
fields, for example.  I think this is an area that would not require
backwards-breaking changes, and so again could be postponed until after 1.0.

  - Ian

On Thu, Feb 25, 2010 at 12:02 AM, Chris Hansen <han...@gm...>wrote:

> I was (re)watching Bloch on API design the other day (
> http://www.infoq.com/presentations/effective-api-design ) and I had a
> couple of takeaways which apply to Pojomatic. We need to discuss/address
> these before it's too late, meaning before 1.0.
>
> 1) Provide programmatic access to all data available in string form.  Among
> other things, this prevents users from parsing the string output.
> 1a) We can, and I think should, refactor the Differences API for
> programmatic access. We could take a page out of the Google Collections book
> on this one:
> http://google-collections.googlecode.com/svn/trunk/javadoc/com/google/common/collect/MapDifference.html
>
> I will work on this one.
>
> 2) Design for extensibility. If you have a successful API, the users will
> want to do more with it. Even if you get the API right the first time, you
> won't get it complete the first time.
> 2a) One way to do this would be to implement extension separately from the
> existing hashCode(), equals(Object), and toString() functionality. That
> would be a small API change which could be done as a point release after
> 1.0, but then existing functionality would be inconsistent with the
> extensible API and might even become a candidate for deprecation at that
> point.
> 2b) Another way to go would be to create the extensible API and refactor
> the existing functionality to use that API right away. This is worse in the
> short term because it delays 1.0, but might pay off in the long term.
>
> To me, the question is not if we should create an extensible API, but when.
> What do you think?
>
> Thanks,
> -Chris
>
>
> ------------------------------------------------------------------------------
> Download Intel&#174; Parallel Studio Eval
> Try the new software tools for yourself. Speed compiling, find bugs
> proactively, and fine-tune applications for parallel performance.
> See why Intel Parallel Studio got high marks during beta.
> http://p.sf.net/sfu/intel-sw-dev
> _______________________________________________
> Pojomatic-users mailing list
> Poj...@li...
> https://lists.sourceforge.net/lists/listinfo/pojomatic-users
>
>