Encapsulating java collections

[Chuck Krutsinger]

I'm really enjoying "Growing Object-Oriented Software, Guided By
Tests". About halfway through and learning a great deal. In it, you
guys wrote:

"Encapsulate Collections - We've developed a habit of packaging up
common types, such as Collections, in our own classes, even though
Java generics avoid the need to cast objects…"

I'm intrigued, but I didn't see an example of this in the book. Do
you have any code sample that illustrates this?

[Steve Freeman]

I don't remember if we actually use it in the book. Our original plan was that the example would be larger.

An example might be wrapping Collection<Subscriber> in a Subscribers type, rather than passing around the collection. I usually find that these wrapper objects start to attract related behaviour, rather than having actions on the collection scattered around the code. One clue is when I get to three levels of angle bracket :)

S.

[Eric Lefevre-Ardant]

Right, but that sounds like regular Encapsulation. The quote that Chuck gave makes me think that, at least at some point, you had in mind to encapsulate a normal ArrayList into MyArrayList with a mostly similar API (although to justify its existence, it better had other features).
I remember doing something similar in the past with Swing classes (almost each class, say JPanel, JButton would have an equivalent, say APanel, AButton).

I no longer think that was a good idea.

However, I can see how a similar approach would let me easily mock up MyArrayList when I pass it to my more business-oriented Subscribers class, hence letting me test it easily.
On the other hand, mocking ArrayList is easy anyway, at least with modern mock frameworks.

[Steve Freeman]

To clarify, my intention was to mean encapsulation. As you said, extending basic collections (at least in Java) probably isn't the best idea.

As a side point, I wouldn't recommend mocking an ArrayList either. It's simpler just to use a real one and it doesn't help to discover domain collaborations.

S.

Steve Freeman

Winner of the Agile Alliance Gordon Pask award 2006
Book: http://www.growing-object-oriented-software.com

+44 797 179 4105
Twitter: @sf105
Higher Order Logic Limited
Registered office. 2 Church Street, Burnham, Bucks, SL1 7HZ.
Company registered in England & Wales. Number 7522677

[Eric Lefevre-Ardant]

Agreed. I rarely mock the JDK's collections. The one case I was thinking of is when writing one's own DelegatingArrayList (although I don't think I've ever done that in practice).

[Steve Freeman]

you French--theory over practice! :)

S.

[Kevin Rutherford]

Hi Chuck,

On Sat, Apr 21, 2012 at 11:06 PM, Chuck Krutsinger
<chuck.kr...@gmail.com> wrote:
>
> "Encapsulate Collections - We've developed a habit of packaging up
> common types, such as Collections, in our own classes, even though
> Java generics avoid the need to cast objects…"

I use a couple of rules to help steer me in the right direction:

1. Never pass a collection as a method parameter or return value
2. Any class that has a collection as an instance variable must have
no other instance variables.

These aren't hard guidelines, but they do push me towards wrapping
most collections in a class. That class will only have methods that
correspond to the ways it is actually used, and will generally not
expose the collection at all.
Cheers,
Kevin
--
http://www.kevinrutherford.co.uk
http://myonepage.com/kevinrutherford
+44 (0) 797 356 3521

[Daniel Yokomizo]

I've been using this rule too with good success. I don't find as
enlightening as separating objects from values or categorizing peers
but it's been a fruitful effort.

IME I find it useful in two situations:

1. Some collections are used as values, and I strive to always make
them immutable. If you don't use a persistent
(https://en.wikipedia.org/wiki/Persistent_data_structure) collections
library you'll end up having to create specialized classes anyway,
because you'll often need to add and remove things from the immutable
collection. Event if you're using a persistent collection library it's
good to have a class representing a bunch of something that can
"attract" the methods using the bunch (from this excellent
presentation on value objects http://vimeo.com/13549100, slides here
http://qconlondon.com/london-2009/file?path=/qcon-london-2009/slides/DanBerghJohnsson_ThePowerOfValuePowerUseOfValueObjectsInDomainDrivenDesign.pdf).

2. Some collections are used as mutable objects, peers to other
objects. In these cases I usually have them as notifications or
dependencies. As I test drive them using mocks I try to not start
using them as List<Something> or Iterable<Whatever> but I try to use a
more descriptive interface to describe the role they play. Most of the
time I prefer to avoid having these interfaces extend the collections
interfaces (though I usually break this rule for the Iterable<T>
interface in Java) but let the tests find which methods need to be
there. Usually no collection methods appears in tests because I
usually find better names more domain oriented.

I think both are reactions to a generalized form of the primitive
obsession smell: code in some domain should only be written using
domain primitives not host language primitives. So it's ok to write
contracts in terms of Obligation and Party, but not in terms of
Integer, String or List<T>. Eventually you end up having to use host
language primitives, but these are used only inside a domain primitive
(which is the smallest concept in a domain that can't be decomposed in
domain language). For example, in an e-commerce application it's
better to have Price, Discount, SuggestedPrice than have Money
everywhere. OTOH you have Money inside these classes, because they're
your domain primitives. Similarly Money is written using some kind
Decimal and Currency.

These usually form an hierarchy of domains/languages each
encapsulating those below it to expose a better API for those above.

[Michał Piotrkowski]

Jimmy Nilsson in his "Applying Domain Driven Design and Patterns" suggests another way of encapsulating collections (original code was in C#, but I translated it to Java):

public class Person {

private List<Person> children = new ArrayList<Person>();

// ...

public Collection<Person> getChildren (){
  return Collections.unmodifableList (children);
}

public void addChild(Person child){
  children.add(child);
}

// ...
}

I like this because it its very simple. It is default solution for me.

When (after a while) I spot a lot of collection handling code in Person. I refactor by applying "extract class" People.

[Chuck Krutsinger]

Thanks everybody. This is a very helpful discussion for me. My
career path took me away from programming for a number of years and
now that I've back into it these last three years, I find I have much
catching up to do. I have had to teach myself quite a bit, so pardon
me if my questions seem naive.

That said, I try to give a concrete example of what I'm getting from
this discussion. Here is a possible class that encapsulates a
collection, but only exposes actions that are expressed in the
ubiquitous language of the domain. Starting with a test:

@Test
public void testEnrolledStudentShouldBeInActiveStudents() {
ActiveStudents mathStudents = new ActiveStudents();
Student aStudent = new Student("Charles Krutsinger");
mathStudents.enroll(aStudent);
assertTrue(mathStudents.isEnrolled(aStudent);
}

Now the implementation:

public class ActiveStudents {

private List<Student> mActiveStudents = new ArrayList<Student>();

public void enroll(Student aStudent) {
mActiveStudents.add(aStudent);
}

public boolean isEnrolled(Student aStudent) {
return mActiveStudents.contains(aStudent);
}

}

I also assume that there is more that one way to do this, but am I on
the right track with this approach? Is this what was meant in the
GOOSGBT book by "Encapsulate Collections"?


On Apr 22, 8:24 am, Michał Piotrkowski

<mpi.michal.piotrkow...@gmail.com> wrote:
> Jimmy Nilsson in his "Applying Domain Driven Design and Patterns" suggests
> another way of encapsulating collections (original code was in C#, but I
> translated it to Java):
>
> public class Person {
>
> private List<Person> children = new ArrayList<Person>();
>
> // ...
>
> public Collection<Person> getChildren (){
>   return Collections.unmodifableList (children);
>
> }
>
> public void addChild(Person child){
>   children.add(child);
>
> }
>
> // ...
>
> }
>
> I like this because it its very simple. It is default solution for me.
>
> When (after a while) I spot a lot of collection handling code in Person. I
> refactor by applying "extract class" People.
> 22-04-2012 14:38, "Kevin Rutherford" <ke...@rutherford-software.com>
> napisał(a):
>
>
>
>
>
>
>
> > Hi Chuck,
>
> > On Sat, Apr 21, 2012 at 11:06 PM, Chuck Krutsinger
> > <chuck.krutsin...@gmail.com> wrote:
>
> > > "Encapsulate Collections - We've developed a habit of packaging up
> > > common types, such as Collections, in our own classes, even though

> > > Java generics avoid the need to cast objects..."

[Steve Freeman]

It's hard to say whether this is the right thing without more context. I suggest you push on it for a while and see where it starts to cause problems. That will show you the limits of the design.

For an example like this, it'll be interesting to see how far you can get without providing some kind access to the collection.

S.

[Colin Vipurs]

This is what we do as much as possible as well.

I found that when people start to do it it comes across as overhead,
but it saves alot of time further down the road and avoids all of
those nasty utility methods for acting on that collection. One of the
best reasons I ever heard, but can't remember where from now, was that
it gets your domain across clearly and lowers the cognitive load on
figuring out what the collection contains. I believe the example
asked what a List<Book> is? A library? A lending card? No idea without
further digging into the code

--
Maybe she awoke to see the roommate's boyfriend swinging from the
chandelier wearing a boar's head.

Something which you, I, and everyone else would call "Tuesday", of course.

[Steve Freeman]

+1

It also reduces opportunities for mistakes such as having the wrong person remove a book from the library.

S.

[Piotr Przybylak]

Wouldn't "Children" be more appropriate for a class in this case then
"People" ?

--
Best regards
Piotr Przybylak

W dniu 22 kwietnia 2012 16:24 użytkownik Michał Piotrkowski
<mpi.michal....@gmail.com> napisał:

[Michał Piotrkowski]

It depends. It depends if you can attach behavior to a Children class that is specific to a collection of children but is not for a collection of people. Example of such behavior in this case could be children.favoriteToys().
Otherwise, you end up with classes like Parents, Neighbors, Coworkers... All of them could be generalized to "a group of people".
I like to use variable name vs variable type analogy:
String name or Name name?
Lets look at an example:

public class Person {
  private String name;
  private Integer age;
  private Integer salary;
  // ...

Or

ublic class Person {
  private Name name;
  private Age age;
  private Salary salary;
  // ...

Which one is better???

I can't imagine any reasonable behavior that could be attached to Name. It is just a sequence of characters. However Age has some validation rules: age cannot be negative. You could also provide a creational method Age.fromBirthDate(Date birthDate).

When to use Integer age and when Age age?
Eric Evans in "Domain Driven Design" introduces concepts of a "core domain" and a "supporting domain". For example, if I am creating an application that calculates and visualizes currencies exchange rates I can let myself to store address data as String addressLine1, String addressLine2, but I should create a separate class for Currency, Money, ExchangeRate, ...

[Steve Freeman]

Actually it all depends ;). Names can have interesting behaviour, whether the family name comes before the personal name varies by language. In Iceland, i believe, the family name depends on gender. Anything involving people will be weird and complicated. 

Plus a separate type avoids allocating a name to an address field. 

S. 

Sent from my iPad

[James Richardson]

Many things that you couldn't imagine could possibly have behaviour, do in fact have lots, depending on the particular context, so best not to over generalise.

I'm just imagining a scenario, but what about people who are yet to be born, like little johnny's mum signing him up for a school, yet his birthday is both in the future and also probably only accurate to month and year, yet you would still want to perform logic like ' age at start of school year'

James

[Chuck Krutsinger]

I can see an advantage to the latter case when programming in Java,

public class Person {

  private Name name;
  private Age age;
  private Salary salary;
  // ...

because when you make calls to the Person constructor or one of its
methods, there may be an improved readability (with the side affect of
being verbose) in saying:

Person chuck = new Person(new Name("Chuck Krutsinger"), new Age(51),
new Salary(100000));

vs.

Person chuck = new Person("Chuck Krutsinger", 51, 20000);

Because in the latter case you have multiple integer args that are not
distinguished and are sequence dependent. Plus, as the system grows
you may start to add behaviors to Age, Salary, and Name.



On Apr 23, 11:29 pm, Michał Piotrkowski

>  23-04-2012 14:04, "Piotr Przybylak" <piotr.przyby...@gmail.com> napisał(a):
>
>
>
>
>
>
>
> > Wouldn't "Children" be more appropriate for a class in this case then
> > "People" ?
>
> > --
> > Best regards
> > Piotr Przybylak
>
> > W dniu 22 kwietnia 2012 16:24 użytkownik Michał Piotrkowski

> > <mpi.michal.piotrkow...@gmail.com> napisał:

> > > Jimmy Nilsson in his "Applying Domain Driven Design and Patterns"
> > suggests
> > > another way of encapsulating collections (original code was in C#, but I
> > > translated it to Java):
>
> > > public class Person {
>
> > > private List<Person> children = new ArrayList<Person>();
>
> > > // ...
>
> > > public Collection<Person> getChildren (){
> > >   return Collections.unmodifableList (children);
> > > }
>
> > > public void addChild(Person child){
> > >   children.add(child);
> > > }
>
> > > // ...
> > > }
>
> > > I like this because it its very simple. It is default solution for me.
>
> > > When (after a while) I spot a lot of collection handling code in Person.
> > I
> > > refactor by applying "extract class" People.
>
> > > 22-04-2012 14:38, "Kevin Rutherford" <ke...@rutherford-software.com>
> > > napisał(a):
>
> > >> Hi Chuck,
>
> > >> On Sat, Apr 21, 2012 at 11:06 PM, Chuck Krutsinger
> > >> <chuck.krutsin...@gmail.com> wrote:
>
> > >> > "Encapsulate Collections - We've developed a habit of packaging up
> > >> > common types, such as Collections, in our own classes, even though

> > >> > Java generics avoid the need to cast objects..."

[James Richardson]

You might find that using a static helper method increases readability there.

Rather than new Age(10) etc, see what you think about Age.of(10) Name.of("bob")

James

[Chuck Krutsinger]

I agree. That does read much better!

On Apr 24, 8:56 am, James Richardson <ja...@time4tea.net> wrote:
> You might find that using a static helper method increases readability
> there.
>
> Rather than new Age(10) etc, see what you think about Age.of(10)
> Name.of("bob")
>
> James

> On Apr 24, 2012 3:12 PM, "Chuck Krutsinger" <chuck.krutsin...@gmail.com>

[Daniel Yokomizo]

Another option is using static method names that are similar to the
class name, like these posts advocate:

http://codemonkeyism.com/never-never-never-use-string-in-java-or-at-least-less-often/
http://jessitron.blogspot.com.br/2012/03/strong-typing-in-java-religious.html

I'm trying the combo with(Name)/name() instead of
setName(String)/getName() and it looks good for value objects.

2012/4/24 Chuck Krutsinger <chuck.kr...@gmail.com>:

[James Richardson]

I wrote a blog about this a while ago, as I seemed to do the same thing on every project....

http://www.time4tea.net/wiki/x/AwA0

James

[Nat Pryce]

Yes. I like to distinguish between value objects that have no
identity and "entity" objects that do have identity. I use the "of"
convention for values, because I don't care if values are represented
as different instances or not. I use new for entities, because I do
care when instances are created and their ongoing lifecycle.

--Nat

2012/4/24 James Richardson <ja...@time4tea.net>:

--
http://www.natpryce.com

[Tim Wood]

I find myself creating builders that work like this:

Person chuck = person().withName("Chuck
Krutsinger").withAge(51).withSalary(100000).build();

I can have multiple occurrences of the method name for different data
types, e.g.

class PersonBuilder {
public PersonBuilder withName(final String name) {
return withName(new Name(name));
}

public PersonBuilder withName(final Name name) {
[...]
}

[...]
}

The disadvantage of this is it is harder to distinguish mandatory
parameters from optional ones, if such a distinction is relevant.

[Eric Lefevre-Ardant]

If knowing from the API what fields are mandatory is important, you could maybe have static methods such as
personOfName("Chuck") or personWithNameAndOfAge("Chuck", 51).
And still use the other with() methods for optional fields.

[Chuck Krutsinger]

Tim, I've used those types of builders as well. There is a good
discussion at the following link about how to structure a builder
grammatically. This results in a wizard-like builder (some would
label an EDSL) that can force the code to only use valid combinations
of builder calls.

<a target="_blank" rel=nofollow href="http://www.javacodegeeks.com/
2012/01/wizard-design-pattern.html#ixzz1rm83hM2h">link to article</a>

> > On Apr 23, 11:29 pm, Micha³ Piotrkowski

> >>  23-04-2012 14:04, "Piotr Przybylak" <piotr.przyby...@gmail.com> napisa³(a):

>
> >> > Wouldn't "Children" be more appropriate for a class in this case then
> >> > "People" ?
>
> >> > --
> >> > Best regards
> >> > Piotr Przybylak
>

> >> > W dniu 22 kwietnia 2012 16:24 u¿ytkownik Micha³ Piotrkowski
> >> > <mpi.michal.piotrkow...@gmail.com> napisa³:

> >> > > Jimmy Nilsson in his "Applying Domain Driven Design and Patterns"
> >> > suggests
> >> > > another way of encapsulating collections (original code was in C#, but I
> >> > > translated it to Java):
>
> >> > > public class Person {
>
> >> > > private List<Person> children = new ArrayList<Person>();
>
> >> > > // ...
>
> >> > > public Collection<Person> getChildren (){
> >> > >   return Collections.unmodifableList (children);
> >> > > }
>
> >> > > public void addChild(Person child){
> >> > >   children.add(child);
> >> > > }
>
> >> > > // ...
> >> > > }
>
> >> > > I like this because it its very simple. It is default solution for me.
>
> >> > > When (after a while) I spot a lot of collection handling code in Person.
> >> > I
> >> > > refactor by applying "extract class" People.
>
> >> > > 22-04-2012 14:38, "Kevin Rutherford" <ke...@rutherford-software.com>

> >> > > napisa³(a):

[J. B. Rainsberger]

On Tue, Apr 24, 2012 at 06:54, Steve Freeman <st...@m3p.co.uk> wrote:

> Actually it all depends ;). Names can have interesting behaviour, whether
> the family name comes before the personal name varies by language. In
> Iceland, i believe, the family name depends on gender. Anything involving
> people will be weird and complicated.

Yes. The Wikipedia pages on naming conventions in various countries
provides interesting reading.

In Iceland, traditional names -- still the majority -- are
patronymics. I would be Josef Jónsson, literally "Joseph, son of
John". My wife would be "Sara Rónsdóttir", or "Sarah, daughter of
Ron". And, of course, not everyone in Iceland does this, just most.
Some have family names as we understand them.
--
J. B. (Joe) Rainsberger :: http://www.jbrains.ca ::
http://blog.thecodewhisperer.com
Author, JUnit Recipes
Free Your Mind to Do Great Work :: http://www.freeyourmind-dogreatwork.com
Find out what others have to say about me at http://nta.gs/jbrains

[Peter Jaros]

On Tue, Apr 24, 2012 at 6:40 PM, J. B. Rainsberger <m...@jbrains.ca> wrote:
> Yes. The Wikipedia pages on naming conventions in various countries
> provides interesting reading.

And for how to treat names in an application, the W3C has an excellent article:

http://www.w3.org/International/questions/qa-personal-names

It's written about web development, of course, but the ideas are universal.

Peter

[philip schwarz]

> I can't imagine any reasonable behavior that could be attached to Name.

Not even if you break Name down as follows:

class Name
{
private String first;
private String middle;
private String last;

...
}

which Object Calisthenics [1] asks us to consider decomposing as
follows:

class Name
{
private Surname family;
private GivenNames given;
}

class Surname
{
private String family;
}

class GivenNames
{
private List<String> names;
}

where GivenNames could contain first name, middle name, etc.

Philip

On Apr 24, 6:29 am, Michał Piotrkowski

>  23-04-2012 14:04, "Piotr Przybylak" <piotr.przyby...@gmail.com> napisał(a):
>
>
>
>
>
>
>
> > Wouldn't "Children" be more appropriate for a class in this case then
> > "People" ?
>
> > --
> > Best regards
> > Piotr Przybylak
>
> > W dniu 22 kwietnia 2012 16:24 użytkownik Michał Piotrkowski

> > <mpi.michal.piotrkow...@gmail.com> napisał:

> > > Jimmy Nilsson in his "Applying Domain Driven Design and Patterns"
> > suggests
> > > another way of encapsulating collections (original code was in C#, but I
> > > translated it to Java):
>
> > > public class Person {
>
> > > private List<Person> children = new ArrayList<Person>();
>
> > > // ...
>
> > > public Collection<Person> getChildren (){
> > >   return Collections.unmodifableList (children);
> > > }
>
> > > public void addChild(Person child){
> > >   children.add(child);
> > > }
>
> > > // ...
> > > }
>
> > > I like this because it its very simple. It is default solution for me.
>
> > > When (after a while) I spot a lot of collection handling code in Person.
> > I
> > > refactor by applying "extract class" People.
>
> > > 22-04-2012 14:38, "Kevin Rutherford" <ke...@rutherford-software.com>
> > > napisał(a):
>
> > >> Hi Chuck,
>
> > >> On Sat, Apr 21, 2012 at 11:06 PM, Chuck Krutsinger
> > >> <chuck.krutsin...@gmail.com> wrote:
>
> > >> > "Encapsulate Collections - We've developed a habit of packaging up
> > >> > common types, such as Collections, in our own classes, even though

> > >> > Java generics avoid the need to cast objects..."

[philip schwarz]

[1] Object Calisthenics http://www.cs.helsinki.fi/u/luontola/tdd-2009/ext/ObjectCalisthenics.pdf

On Apr 26, 11:10 pm, philip schwarz

<philip.johann.schw...@googlemail.com> wrote:
> > I can't imagine any reasonable behavior that could be attached to Name.
>
> Not even if you break Name down as follows:
>
> class Name
> {
>   private String first;
>   private String middle;
>   private String last;
>
>   ...
>
> }
>
> which Object Calisthenics [1] asks us to consider decomposing as
> follows:
>
> class Name
> {
>     private Surname family;
>     private GivenNames given;
>
> }
>
> class Surname
> {
>     private String family;
>
> }
>
> class GivenNames
> {
>     private List<String> names;
>
> }
>
> where GivenNames could contain first name, middle name, etc.
>
> Philip
>

> On Apr 24, 6:29 am, Micha³ Piotrkowski

> >  23-04-2012 14:04, "Piotr Przybylak" <piotr.przyby...@gmail.com> napisa³(a):

>
> > > Wouldn't "Children" be more appropriate for a class in this case then
> > > "People" ?
>
> > > --
> > > Best regards
> > > Piotr Przybylak
>

> > > W dniu 22 kwietnia 2012 16:24 u¿ytkownik Micha³ Piotrkowski
> > > <mpi.michal.piotrkow...@gmail.com> napisa³:

> > > > Jimmy Nilsson in his "Applying Domain Driven Design and Patterns"
> > > suggests
> > > > another way of encapsulating collections (original code was in C#, but I
> > > > translated it to Java):
>
> > > > public class Person {
>
> > > > private List<Person> children = new ArrayList<Person>();
>
> > > > // ...
>
> > > > public Collection<Person> getChildren (){
> > > >   return Collections.unmodifableList (children);
> > > > }
>
> > > > public void addChild(Person child){
> > > >   children.add(child);
> > > > }
>
> > > > // ...
> > > > }
>
> > > > I like this because it its very simple. It is default solution for me.
>
> > > > When (after a while) I spot a lot of collection handling code in Person.
> > > I
> > > > refactor by applying "extract class" People.
>
> > > > 22-04-2012 14:38, "Kevin Rutherford" <ke...@rutherford-software.com>

> > > > napisa³(a):