Uncle Bob’s Clean Architecture – Composed Entities Explained

androidarchitectural-patternsArchitectureclean code

I'm building an Android application, and trying to follow the Clean Architecture pattern.

I am a little confused on what my entities should look like regarding some of my use cases.

Example

I have a list of channels, and each channel have programs.
I want to display a list of the current program for each channel, and when an element is clicked, I display a channel page with the channel detailed info and the current program info.

Entities

I can see here that I should have a Channel and a Program entity. But should Channel have a field List<Program> programs (as there are mutiple programs during the day)? And another Program currentProgram?
Or should Channel be separated

Use case

Should they return entities, or some dto object?
Currently, my use cases return entities, but are mapped to some dto objects in the presenters.

TL;DR

Which of the proposition below is the way to go?

Pseudo-Code propositions

Case A

Entities

Channel
{
  id()
  name()
  logo()
}

Program
{
  id()
  name()
  thumbnail()
  start_date()
  end_date()
}

Use Cases
List<Channel> GetChannelsUseCase()
Program GetCurrentProgramForChannel(channelId)

Presenter

fetchChannels()
{
    // Builds a List<CurrentProgramViewModel> based on
    // GetChannelsUseCase composed with GetCurrentProgramForChannel for each channel
}

Case B

Entities

Channel
{
  id()
  name()
  logo()
  programs()
}

Program
{
  id()
  name()
  thumbnail()
  start_date()
  end_date()
}

Use Cases
List<Channel> GetChannelsUseCase()

Presenter

fetchChannels()
{
    // Builds a List<CurrentProgramViewModel> based on
    // GetChannelsUseCase and filtering the programs()
    // to extract the 'current' program
}

Case C

Entities

Channel
{
  id()
  name()
  logo()
}

Program
{
  id()
  name()
  thumbnail()
  start_date()
  end_date()
}

Repository
List<Channel> GetChannelsUseCase()
Program GetCurrentProgramForChannel(channelId)

Use Cases
List<ProgramDto> GetCurrentProgramUseCase()

{
    // The Use Case requests the repository to get the entities
    // and builds a ProgramDto object
}

Presenter

fetchChannels()
{
    // Maps a List<CurrentProgramViewModel> based on the
    // List<ProgramDto> returned by GetCurrentProgramUseCase
}

ps: I'll ask about the datasource and repository later / in another topic if necessary

Best Answer

In my experience, a Program isn't permanently tied to a Channel. In fact, a Program can appear on several Channels sometimes even at the same time!

I think you're missing a Listing entity which takes care of associating Programs with a specific time. This means that your Programs should no longer track their start and end times anymore but they probably should track their duration. You might benefit from a Schedule as well to link a Listing with a Channel.

Pseudocode:

Channel
{
  id,
  name,
  logo,
}

Program
{
  id,
  name,
  thumbnail,
  duration,
}

Schedule
{
  channelId,
  date,
  listings = Collection<Listing>
}

Listing
{
  program,
  startTime,
  endTime = () => startTime + program.duration,
}

You would then have a service that allows you to query Schedules base on the channel and date.

Related Solutions

Clean Architecture – Should Each Layer Have Its Own Entity/Model Class?

In my opinion, that's absolutely not how it's meant. And it's a violation of DRY.

The idea is that the entity / domain object in the middle is modeled to represent the domain as good and as convenient as possible. It is in the center of everything and everything can depend on it since the domain itself doesn't change most of the time.

If your database on the outside can store those objects directly, then mapping them to another format for the sake of separating layers is not just pointless but creating duplicates of the model and that is not the intention.

To begin with, the clean architecture was made with a different typical environment / scenario in mind. Business server applications with behemoth outer layers that need their own types of special objects. For example databases that produce SQLRow objects and need SQLTransactions in return to update items. If you were to use those in the center, you were to violate the dependency direction because your core would depend on the database.

With lightweight ORMs that load and store entity objects thats not the case. They do the mapping between their internal SQLRow and your domain. Even if you need put an @Entitiy annotation of the ORM into your domain object, I'd argue that this does not establish a "mention" of the outer layer. Because annotations are just metadata, no code that isn't specifically looking for them will see them. And more importantly, nothing needs to change if you remove them or replace them with a different database's annotation.

In contrast, if you do change your domain and you made all those mappers, you have to change a lot.

Amendment: Above is a little oversimplified and could even be wrong. Because there is a part in clean architecture that wants you to create a representation per layer. But that has to be seen in context of the application.

Namely the following here https://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.html

The important thing is that isolated, simple, data structures are passed across the boundaries. We don’t want to cheat and pass Entities or Database rows. We don’t want the data structures to have any kind of dependency that violates The Dependency Rule.

Passing entities from the center towards the outer layers does not violate the dependency rule, yet they are mentioned. But this has a reason in the context of the envisioned application. Passing entities around would move the application logic towards the outside. Outer layers would need to know how to interpret the inner objects, they would effectively have to do what inner layers like the "use case" layer is supposed to do.

Besides that, it also decouples layers so that changes to the core don't necessarily require changes in outer layers (see SteveCallender's comment). In that context, it's easy to see how objects should represent specifically the purpose they are used for. Also that layers should talk to each other in terms of objects that are made specifically for the purpose of this communication. This can even mean that there are 3 representations, 1 in each layer, 1 for transport between layers.

And there is https://blog.8thlight.com/uncle-bob/2011/11/22/Clean-Architecture.html which addresses above:

Other folks have worried that the net result of my advice would be lots of duplicated code, and lots of rote copying of data from one data structure to another across the layers of the system. Certainly I don’t want this either; and nothing I have suggested would inevitably lead to repetition of data structures and an inordinate of field copying.

That IMO implies that plain 1:1 copying of objects is a smell in the architecture because you're not actually using the proper layers and /or abstractions.

He later explains how he imagines all the "copying"

You separate the UI from the business rules by passing simple data structures between the two. You don’t let your controllers know anything about the business rules. Instead, the controllers unpack the HttpRequest object into a simple vanilla data structure, and then pass that data structure to an interactor object that implements the use case by invoking business objects. The interactor then gathers the response data into another vanilla data structure and passes it back to the UI. The views do not know about the business objects. They just look in that data structure and present the response.

In this application, there is a big difference between the representations. The data that flows isn't just the entities. And this warrants and demands different classes.

However, applied to a simple Android application like a photo viewer where the Photo entity has about 0 business rules and the "use case" that deals with them is nearly non-existing and is actually more concerned about caching & downloading (that process should IMO be represented more explicitly), the point to make separate representations of a photo starts to vanish. I even get the feeling that the photo itself is the data transfer object while the real business-logic-core-layer is missing.

There is a difference between "separate the UI from the business rules by passing simple data structures between the two" and "when you want to display a photo rename it 3 times on the way".

Besides that, the point where I see those demo applications fail at representing the clean architecture is that they add huge emphasis on separating layers for the sake of separating layers but effectively hide what the application does. That is in contrast to what is said in https://blog.8thlight.com/uncle-bob/2011/09/30/Screaming-Architecture.html - namely that

the architecture of a software application scream about the use cases of the application

I don't see that emphasis on separating layers in the clean architecture. It's about dependency direction and focusing on representing the core of the application - entities and use cases - in ideally plain java without dependencies towards the outside. It's not so much about dependencies towards that core.

So if your application actually has a core that represents business rules and use cases, and / or different people work on different layers, please separate them in the intended way. If you're on the other hand just writing a simple app all by yourself don't overdo it. 2 layers with fluent bounds may be more than enough. And layers can be added later on as well.

Clean Architecture – Use Case with Presenter or Returning Data

The Clean Architecture suggests to let a use case interactor call the actual implementation of the presenter (which is injected, following the DIP) to handle the response/display. However, I see people implementing this architecture, returning the output data from the interactor, and then let the controller (in the adapter layer) decide how to handle it.

That's certainly not Clean, Onion, or Hexagonal Architecture. That is this:

Not that MVC has to be done that way

You can use many different ways to communicate between modules and call it MVC. Telling me something uses MVC doesn't really tell me how the components communicate. That isn't standardized. All it tells me is that there are at least three components focused on their three responsibilities.

Some of those ways have been given different names:

And every one of those can justifiably be called MVC.

Anyway, none of those really capture what the buzzword architectures (Clean, Onion, and Hex) are all asking you to do.

Add the data structures being flung around (and flip it upside down for some reason) and you get:

One thing that should be clear here is that the response model does not go marching through the controller.

If you are eagle eye'd, you might have noticed that only the buzzword architectures completely avoid circular dependencies. That means the impact of a code change won't spread by cycling through components. The change will stop when it hits code that doesn't care about it.

Wonder if they turned it upside down so that the flow of control would go through clockwise. More on that, and these "white" arrow heads, later.

Is the second solution leaking application responsibilities out of the application layer, in addition to not clearly defining input and output ports to the interactor?

Since communication from Controller to Presenter is meant to go through the application "layer" then yes making the Controller do part of the Presenters job is likely a leak. This is my chief criticism of VIPER architecture.

Why separating these is so important could probably be best understood by studying Command Query Responsibility Segregation.

#Input and output ports

Considering the Clean Architecture definition, and especially the little flow diagram describing relationships between a controller, a use case interactor, and a presenter, I'm not sure if I correctly understand what the "Use Case Output Port" should be.

It's the API that you send output through, for this particular use case. It's no more than that. The interactor for this use case doesn't need to know, nor want to know, if output is going to a GUI, a CLI, a log, or an audio speaker. All the interactor needs to know is the very simplest API possible that will let it report the results of it's work.

Clean architecture, like hexagonal architecture, distinguishes between primary ports (methods) and secondary ports (interfaces to be implemented by adapters). Following the communication flow, I expect the "Use Case Input Port" to be a primary port (thus, just a method), and the "Use Case Output Port" an interface to be implemented, perhaps a constructor argument taking the actual adapter, so that the interactor can use it.

The reason the output port is different from the input port is that it must not be OWNED by the layer that it abstracts. That is, the layer that it abstracts must not be allowed to dictate changes to it. Only the application layer and it's author should decide that the output port can change.

This is in contrast to the input port which is owned by the layer it abstracts. Only the application layer author should decide if it's input port should change.

Following these rules preserves the idea that the application layer, or any inner layer, does not know anything at all about the outer layers.

#On the interactor calling the presenter

The previous interpretation seems to be confirmed by the aforementioned diagram itself, where the relation between the controller and the input port is represented by a solid arrow with a "sharp" head (UML for "association", meaning "has a", where the controller "has a" use case), while the relation between the presenter and the output port is represented by a solid arrow with a "white" head (UML for "inheritance", which is not the one for "implementation", but probably that's the meaning anyway).

The important thing about that "white" arrow is that it lets you do this:

You can let the flow of control go in the opposite direction of dependency! That means the inner layer doesn't have to know about the outer layer and yet you can dive into the inner layer and come back out!

Doing that has nothing to do with using the "interface" keyword. You could do this with an abstract class. Heck you could do it with a (ick) concrete class so long as it can be extended. It's simply nice to do it with something that focuses only on defining the API that Presenter must implement. The open arrow is only asking for polymorphism. What kind is up to you.

Why reversing the direction of that dependency is so important can be learned by studying the Dependency Inversion Principle. I mapped that principle onto these diagrams here.

#On the interactor returning data

However, my problem with this approach is that the use case must take care of the presentation itself. Now, I see that the purpose of the Presenter interface is to be abstract enough to represent several different types of presenters (GUI, Web, CLI, etc.), and that it really just means "output", which is something a use case might very well have, but still I'm not totally confident with it.

No that's really it. The point of making sure the inner layers don't know about the outer layers is that we can remove, replace, or refactor the outer layers confident that doing so wont break anything in the inner layers. What they don't know about won't hurt them. If we can do that we can change the outer ones to whatever we want.

Now, looking around the Web for applications of the clean architecture, I seem to only find people interpreting the output port as a method returning some DTO. This would be something like:

Repository repository = new Repository();
UseCase useCase = new UseCase(repository);
Data data = useCase.getData();
Presenter presenter = new Presenter();
presenter.present(data);
// I'm omitting the changes to the classes, which are fairly obvious

This is attractive because we're moving the responsibility of "calling" the presentation out of the use case, so the use case doesn't concern itself with knowing what to do with the data anymore, rather just with providing the data. Also, in this case we're still not breaking the dependency rule, because the use case still doesn't know anything about the outer layer.

The problem here is now whatever knows how to ask for the data has to also be the thing that accepts the data. Before the Controller could call the Usecase Interactor blissfully unaware of what the Response Model would look like, where it should go, and, heh, how to present it.

Again, please study Command Query Responsibility Segregation to see why that's important.

However, the use case doesn't control the moment when the actual presentation is performed anymore (which may be useful, for example to do additional stuff at that point, like logging, or to abort it altogether if necessary). Also, notice that we lost the Use Case Input Port, because now the controller is only using the getData() method (which is our new output port). Furthermore, it looks to me that we're breaking the "tell, don't ask" principle here, because we're asking the interactor for some data to do something with it, rather than telling it to do the actual thing in the first place.

Yes! Telling, not asking, will help keep this object oriented rather than procedural.

#To the point

So, is any of these two alternatives the "correct" interpretation of the Use Case Output Port according to the Clean Architecture? Are they both viable?

Anything that works is viable. But I wouldn't say that the second option you presented faithfully follows Clean Architecture. It might be something that works. But it's not what Clean Architecture asks for.

Example

Entities

Use case

TL;DR

Pseudo-Code propositions

Case A

Case B

Case C

Best Answer

Related Solutions

Clean Architecture – Should Each Layer Have Its Own Entity/Model Class?

Clean Architecture – Use Case with Presenter or Returning Data

Related Topic