DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations
Building Scalable Real-Time Apps with AstraDB and Vaadin
Register Now

Trending

  • WireMock: The Ridiculously Easy Way (For Spring Microservices)
  • Designing a New Framework for Ephemeral Resources
  • A Data-Driven Approach to Application Modernization
  • Effective Java Collection Framework: Best Practices and Tips

Trending

  • WireMock: The Ridiculously Easy Way (For Spring Microservices)
  • Designing a New Framework for Ephemeral Resources
  • A Data-Driven Approach to Application Modernization
  • Effective Java Collection Framework: Best Practices and Tips
  1. DZone
  2. Software Design and Architecture
  3. Microservices
  4. How to Organize Your Code

How to Organize Your Code

Code organization is more an art than a science. See how the folks over at Hello2morrow do it here.

Alexander Von Zitzewitz user avatar by
Alexander Von Zitzewitz
·
Sep. 05, 16 · Opinion
Like (29)
Save
Tweet
Share
23.70K Views

Join the DZone community and get the full member experience.

Join For Free

In this article I am going to present a realistic example that will show you how to organize your code and how to describe this organization using our architecture DSL (domain specific language) implemented by our static analysis tool Sonargraph-Architect. Let us assume we are building a micro-service that manages customers, products and orders. A high level architecture diagram would look like this:

System Architecture

It is always a good idea to cut your system along functionality, and here we can easily see three subsystems. In Java you would map those subsystems to packages, in other languages you might organize your subsystem into separate folders on your file system and use namespaces if they are available. 

Let us assume the system is written in Java and its name is “Order Management”. In that case we would organize the code into those 3 packages:

com.hello2morrow.ordermanagement.order
com.hello2morrow.ordermanagement.customer
com.hello2morrow.ordermanagement.product

This can easily be mapped to our architecture DSL:

artifact Order
{
    include "**/order/**"
    connect to Customer, Product
}

artifact Customer
{
    include "**/customer/**"
}

artifact Product
{
    include "**/product/**"
}

Internally all three subsystem have a couple of layers and the layering is usually the same for all subsystems. In our example we have four layers: 

Layering

A service would only expose its service ad its model layer to the outside. The service layer contains all the service interfaces and talks to the controller and the model layer. The controller layer contains all the business logic and uses the data access layer to retrieve or persist data using JDBC. The model layer defines the entities used by our microservice.

We will use a separate architecture file named “layering.arc” to describe our layering:

// layering.arc
artifact Service
{
    include "**/service/**"
    connect to Controller
}

artifact Controller
{
    include "**/controller/**"
    connect to DataAccess
}

require "JDBC"

artifact DataAccess
{
    include "**/data/**"
    connect to JDBC
}

public artifact Model
{
    include "**/model/**"
}

interface IService
{
    export Service, Model
}

Please note that we declared “Model” as a public artifact. That saves us the need to explicitly connect all the other layers to “Model”. Also note the “require” statement. Here refer to a third architecture file, that contains the definition of the artifact JDBC. This way we can ensure that only the data access layer can make JDBC calls. Using “require” will only declare the artifacts contained in the required file, but not define them. This means that the artifacts in “JDBC” have to be defined on another level. The interface is used to define the exposed parts of a subsystem. When connecting to the “IService” interface you have only access to the “Service” and the “Model” layer.

Now we use apply statements to apply the layering to our three subsystems:

artifact Order
{
    include "**/order/**"
    apply "layering"
    // Connect to the IService interface of Customer and Product
    connect to Customer.IService, Product.IService
}

artifact Customer
{
    include "**/customer/**"
    apply "layering"
}

artifact Product
{
    include "**/product/**"
    apply "layering"
}

// By using apply we define the artifacts of "JDBC" in this scope
apply "JDBC"

We also apply “JDBC” in the outermost scope to ensure that the artifacts in there are defined exactly once.

For the sake of completeness, here is the definition of “JDBC.arc”

artifact JDBC
{
    include "**/javax/sql/**"
}

By using smart package naming it becomes easy to map your code to the architecture description. For example the order subsystem would have four packages:

com.hello2morrow.ordermanagement.order.service
com.hello2morrow.ordermanagement.order.controller
com.hello2morrow.ordermanagement.order.data
com.hello2morrow.ordermanagement.order.model

As you can see it required relatively little effort to create a formal and enforceable architecture description for a software system. If you want to learn more about our architecture DSL, I recommend reading a series of blog posts introducing the different concepts of this powerful language.

File system Data access layer Architecture

Published at DZone with permission of Alexander Von Zitzewitz, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Trending

  • WireMock: The Ridiculously Easy Way (For Spring Microservices)
  • Designing a New Framework for Ephemeral Resources
  • A Data-Driven Approach to Application Modernization
  • Effective Java Collection Framework: Best Practices and Tips

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com

Let's be friends: