DCL Manual

1. In Eclipse, click on Help > Install New Software...
2. Click Add....
3. Enter the following:
   • Name: DCL
   • URL: http://aserg.labsoft.dcc.ufmg.br/dclsuite/update
   and click OK.
4. You should see Architecture Conformance Tools item under the field name.
   Click on the triangle next to it to make dclsuite visible in the tree.
5. Click the checkbox next to it to select it, and click Next.
6. After reviewing the items to be installed, go next.
7. After accepting the license, finish.
8. The plugin is not digitally signed. Go ahead and install it anyway.
9. Click Restart Now to make Eclipse restart itself.
10. Done. DCLsuite is now ready for use.

The procedure above is also explained using this video.

4.1.1. Kinds of Constraints

In order to capture divergences, DCL supports the definition of the following kinds of constraints between modules:

• only MA can-dep MA : Only classes of module MA can depend on types defined in module MB. The literal dep refers to dependency type, which can be either more generic (depend) or more specific (access, declare, create, extend, implement, throw, and useannotation). For example, the constraint only DAOFactory can-create DAO defines that only a factory class can create data access objects.

• MA can-dep-only MB: Classes of module MA can depend only on types defined in module MB. For example, the constraint Util can-depend-only Util, $java defines that utility classes can only depend on their own classes or Java API classes.

• MA cannot-dep MB: Classes of module MA cannot depend on types defined in module MB. For example, the constraint Facade cannot-handle DTO defines that facade classes cannot manipulate entity classes.


4.1.2. Examples

4.1.2.1. access (using only can)
A constraint in the form only M_A can-access M_B indicates that only classes declared in module M_A can access nonprivate members of classes declared in module M_B. Access in this case means calling methods, reading or writing to fields.


Example. Assume the following DCL constraints:
 1: module Formulas: org.foo.formulas.*
 2: only Formulas can-access java.lang.Math 

In this example, module Formulas groups the classes from package org.foo.formulas (line 1). Then, in line 2, a restriction only allows module Formulas to access the standard Java class that provides mathematical operations. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.2. declare (using can-only)
A constraint in the form M_A can-declare-only M_B indicates that classes declared in module M_A can declare only variables of types declared in module M_B.


Example. Assume the following DCL constraints:
 1: module DomainFacades: org.foo.facades.*
 2: module Domain: org.foo.model.Domain+
 3: DomainFacades can-declare-only Domain, $java 

In this example, module DomainFacades groups all facade classes (line 1) and module Domain refers to domain classes, i.e., subclasses from org.foo.model.Domain (line 2). Then, in line 3, a constraint defines that module DomainFacades can declare only domain objects and types of Java library. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.3. handle (using cannot)
Acronym for  cannot-access, cannot-declare.


4.1.2.4. create (using only can)
A constraint in the form only M_A can-create M_B indicates that only classes declared in module M_A can create objects of classes declared in module M_B.


Example. Assume the following DCL constraints:
 1: module Factory: org.foo.Factory
 2: module Product: org.foo.Product+
 3: only Factory can-create Product

In this example, module Factory contains only the class org.foo.Factory (line 1) and module Product groups the class org.foo.Product and its subclasses (line 2). Then, in line 3, a constraint defines that only module Factory can create products, i.e., instantiate classes from module Product. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.5. extend (using only can)
A constraint in the form only M_A can-extend M_B indicates that only classes declared in module M_A can extend classes declared in module M_B.


Example. Assume the following DCL constraints:
 1: module Servlets: org.foo.controller.servlets.*
 2: module BaseHttpServlet: javax.servlet.http.HttpServlet
 3: only Servlets can-extend BaseHttpServlet 

In this example, module Servlets contains all classes from package org.foo.controller.servlets (line 1) and module BaseHttpServlet refers to the class javax.servlet.http.HttpServlet, which is the default Java class to handle requests and responses using the HTTP protocol (line 2). Then, in line 3, a restriction ensures that only classes from module Servlets are allowed to extend the class javax.servlet.http.HttpServlet. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.6. implement (using can-only)
A constraint in the form M_A can-implement-only M_B indicates that classes declared in module M_A can implement only interfaces declared in module M_B.


Example. Assume the following DCL constraints:
 1: module Filters: "org.foo.[a-zA-Z0-9/.]*Filter"
 2: Filters can-implement-only java.util.EventListener

In this example, module Filters groups the classes from package org.foo that have sufix Filter (line 1). Then, in line 2, a constraint defines that classes from module Filters can implement only the interface java.util.EventListener. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.7. derive (using cannot)
Acronym for  cannot-extend, cannot-implement.


4.1.2.8. throw (using cannot)
A constraint in the form M_A cannot-throw M_B indicates that no methods from classes declared in module M_A can throw exceptions declared in module M_B.


Example. Assume the following DCL constraints:
 1: module DAO: "org.foo.model.dao.[a-zA-Z0-9/.]*DAO"
 2: DAO cannot-throw java.sql.SQLException+

In this example, the module DAO contains classes from package org.foo.model.dao that have suffix DAO (line 1). Then, in line 2, a restriction prohibits that methods from DAO classes returns with exceptions from JDBC library activated (i.e., exceptions like java.sql.SQLException and its subclasses). Otherwise, DCL will report an architectural violation (divergence).


4.1.2.9. useannotation (using cannot)
A constraint in the form M_A cannot-useannotation M_B indicates that no classe declared in module M_A can use annotations declared in module M_B.


Example. Assume the following DCL constraints:
 1: $system cannot-useannotation java.lang.SuppressWarnings

In this example, it was not necessary to define a module, since DCL provides the default module $system, which refers to the class of the system under analysis. Therefore, this restriction prohibits any class of the system to use the annotation java.lang.SuppressWarnings, which is a native annotation of Java responsible for suppressing warnings. Otherwise, DCL will report an architectural violation (divergence).


4.1.2.10. depend (using cannot)
A constraint in the form M_A cannot-depend M_B indicates that classes declared in module M_A cannot depend on classes declared in module M_B. Thus, depend refers to any kind of dependence, i.e., access, declare, etc.

4.2.1. Kinds of Constraints

In order to capture absences, DCL supports the definition of the following constraints:

• MA must-dep MB: Classes of module MA must depend on types defined in module MB. For example, the constraint DTO must-implement java.io.Serializable defines that entity classes must implement Java’s serializable interface.


4.2.2. Examples

4.2.2.1. extend (using must)
A constraint in the form M_A must-extend M_B indicates that all classes declared in module M_A must extend a class declared in module M_B.


Example. Assume the following DCL constraints:
 1: module Servlets: org.foo.controller.servlets.*
 2: module BaseHttpServlet: javax.servlet.http.HttpServlet
 3: Servlets must-extend BaseHttpServlet

In this example, module Servlets contains the classes of package org.foo.controller.servlets (line 1) and module BaseHttpServlet refers to class javax.servlet.http.HttpServlet, which is the standard class to handle requests and responses using HTTP protocol. Then, in line 3, a constraint requires that the classes of module Servlets extend the class javax.servlet.http.HttpServlet. Otherwise, DCL will report an architectural violation (absence).


4.2.2.2. implement (using must)
A constraint in the form M_A must-implement M_B indicates that all classes declared in module M_A must implement at least an interface declared in module M_B.


Example. Assume the following DCL constraints:
 1: module Filters: "org.foo.[a-zA-Z0-9/.]*Filter"
 2: Filters must-implement java.util.EventListener

In this example, module Filters groups classes from package org.foo that have suffix Filter (line 1). Then, in line 2, a constraint requires that classes from module Filters must implement the interface java.util.EventListener. Otherwise, DCL will report an architectural violation (absence).



4.2.2.3. derive (using must)

Acronym for  must-extend, must-implement.



4.2.2.4. throw (using must)

A constraint in the form M_A must-throw M_B indicates that all methods from classes declared in module M_A must declare that they can return with exceptions declared in module M_B raised.



Example. Assume the following DCL constraints:

 1: module DAO: org.foo.model.dao.impl.*
 2: module DAOException: org.foo.model.dao.DAOException
 3: DAO must-throw DAOException


In this example, module DAO groups all classes of package org.foo.model.dao.impl (line 1) and module DAOException (line 2) refers to class org.foo.model.dao.DAOException. Then, in line 3, a constraint requires that all methods declared in module DAO must declare that they can return with exceptions declared in module DAOException. Otherwise, DCL will report an architectural violation (absence).



4.2.2.5. useannotation (using must)

A constraint in the form M_A must-useannotation M_B indicates that all classes declared in module M_A must use at least an annotation declared in module M_B.



Example. Assume the following DCL constraints:

 1: module DTO: org.foo.model.dto.*
 2: module JPA: javax.persistence.**
 3: DTO must-useannotation JPA


In this example, module DTO (line 1) groups all classes of package org.foo.model.dto and module JPA (line 2) includes classes of javax.persistence and its internal packages. Then, in line 3, a constraint requires that all classes in module DTO must use at least an annotation declared in module JPA. Otherwise, DCL will report an architectural violation (absence).