Code Query Language 1.8 Specification CQL 1.8 CQL 1.8 is supported by XDepend 1.0RC2 and higher Copyright SMACCHIA.COM S.A.R.L 2006/2007/2008/2009 Copyright OCTO Technology 2009 All rights reserved

Content

Introduction

CQL is a language which allows writing queries on the code structure of any JAVA application.
For example, the following CQL query returns all the methods of your application with more than 200 BC (ByteCode) instructions, ordered from the biggest to the smallest:

 
SELECT METHODS WHERE NbBCInstructions > 200 ORDER BY NbBCInstructions DESC

You might wish to avoid methods with more than 200 BC instructions since they are hard to maintain.
After having shrunk all your methods, you certainly want to be notified when during development a method exceeds this threshold.
The CQL language addresses this need by allowing the transformation of queries into constraints.
For example, here is our previous query rewritten as a constraint:

WARN IF Count > 0 IN SELECT METHODS WHERE NbBCInstructions > 200 ORDER BY NbBCInstructions DESC

With almost a hundred keywords, the CQL language allows you to deal with various conditions on your code structure.
It allows to write

• code quality constraints,
• naming constraints,
• design constraints,
• encapsulation constraints,
• queries on the graph of dependencies,
• queries on the inheritance tree,
• queries to get the biggest or smallest code elements according to almost 30 metrics

and much more.

CQL and VisualXDepend

The tool VisualXDepend allows the editing and execution of CQL queries and constraints.
A GUI allows you to have a unique understanding of your application. VisualXDepend can also be used to generate reports during each build of your application.

Learning the CQL language

Writing CQL queries and constraints is straightforward thanks to the three following features:

• The CQL language syntax is close to that of the SQL language syntax. They both share the SELECT TOP xxx FROM xxx WHERE xxx ORDER BY xxx pattern.
• The VisualXDepend CQL editor offers intellisense.
• The VisualXDepend CQL compiler yields verbose errors.

The CQL language and real-world needs

The CQL language has been conceived to understand and control real-world application. In a real-world environment,
there are often exceptions (like automatically generated methods which are often very big) and you need to
allow a few particular methods to exceed this threshold without being bothered by our previous constraint.
The CQL language offers numerous features allowing you to deal with such exceptions.
For example, all generated methods might contain the word in

WARN IF Count > 0 IN SELECT METHODS WHERE  NbBCInstructions > 200 AND !NameLike "Generated" ORDER BY NbBCInstructions DESC

Or maybe, all generated methods are in dedicated jars, packages or types:

 
WARN IF Count > 0 IN SELECT METHODS OUT OF PACKAGES "com.acme.generated1","com.acme.generated2" WHERE NbBCInstructions > 200 ORDER BY NbBCInstructions DESC

Or maybe, you prefer to mention each one explicitly:

 
WARN IF Count > 0 IN SELECT METHODS WHERE NbBCInstructions > 200 AND !(NameIs "method1(int)" OR FullNameIs "com.acme.foo.Bar.doSomething2(String)" ) ORDER BY NbBCInstructions DESC

You can also mix all these features in the same constraint:

 
WARN IF Count > 0 IN SELECT METHODS OUT OF PACKAGES "com.acme.generated1","com.acme.generated2" WHERE NbBCInstructions > 200 AND !(NameIs "method1(int)" OR FullNameIs "com.acme.foo.Bar.doSomething2(String)" ) AND !NameLike "generated" ORDER BY NbBCInstructions DESC

Examples of code Quality constraints

 
WARN IF Count > 0 IN SELECT METHODS WHERE NbBCInstructions > 200 ORDER BY NbBCInstructions DESC
// METHODS WHERE NbBCInstructions > 200 are extremely complex and 
// should be split in smaller methods 
// (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT METHODS WHERE BCCyclomaticComplexity > 40 ORDER BY BCCyclomaticComplexity DESC
// METHODS WHERE BCCyclomaticComplexity > 20 are hard to understand and maintain.
// METHODS WHERE BCCyclomaticComplexity > 40 are extremely complex and should be split 
// in smaller methods (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT METHODS WHERE NbParameters > 5 ORDER BY NbParameters DESC
// METHODS WHERE NbParameters > 5 might be painful to call and might degrade performance. 
// You should prefer using additional properties/fields to the declaring type to handle 
// numerous states. Another alternative is to provide a class or structure dedicated to 
// handle arguments passing.
 
WARN IF Count > 0 IN SELECT METHODS WHERE NbVariables > 15 ORDER BY NbVariables DESC
// METHODS WHERE NbVariables > 8 are hard to understand and maintain.
// METHODS WHERE NbVariables > 15 are extremely complex and should be split in 
// smaller methods (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT TYPES WHERE NbMethods > 20 ORDER BY LCOM DESC
// TYPES WHERE NbMethods > 20 might be hard to understand and maintain 
// but there might be cases where it is relevant to have a high value for NbMethods. 

WARN IF Count > 0 IN SELECT TYPES WHERE NbFields > 20 AND !IsEnumeration 
// TYPES WHERE NbFields > 20 AND !IsEnumeration might be hard to understand and maintain 
// but there might be cases where it is relevant to have a high value for NbFields. 


WARN IF Count > 0 IN SELECT TYPES WHERE SizeOfInst > 64 ORDER BY SizeOfInst DESC
// TYPES WHERE SizeOfInst > 64 might degrade performance (depending on the number of 
// instances created at runtime) and might be hard to maintain. 
// However it is not a rule since sometime there is no alternative 


WARN IF Count > 0 IN SELECT TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10 ORDER BY LCOM DESC
// TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10 might be problematic. 
// However, it is very hard to avoid such non-cohesive types. The LCOMHS metric
// is often considered as more efficient to detect non-cohesive types.

WARN IF Count > 0 IN SELECT TYPES WHERE LCOMHS > 1.0 AND NbFields > 10 AND NbMethods >10 ORDER BY LCOMHS DESC
// TYPES WHERE LCOMHS > 1.0 AND NbFields > 10 AND NbMethods >10 should be avoided. 
// Note that this constraint is stronger than the constraint 
// TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10.

SELECT TYPES WHERE DepthOfInheritance > 6 ORDER BY DepthOfInheritance DESC
// TYPES WHERE DepthOfInheritance > 6 might be hard to maintain. However it is not 
// a rule since sometime your classes might inherit from tier classes which have a 
// high value for depth of inheritance. 

WARN IF Count > 0 IN SELECT TYPES WHERE (SizeOfInst > 200 ) ORDER BY SizeOfInst DESC
// Type with big instances can be problematic 
// (Obviously the SizeOfInst metric does not do a deep traverse.
//  Any instance reference field will count for 4 bytes.
//  It is also unable to cop with generic types properly)

WARN IF Percentage > 15 IN SELECT JARS WHERE NormDistFromMainSeq > 0.7 ORDER BY NormDistFromMainSeq DESC

WARN IF Count > 0 IN SELECT JARS WHERE RelationalCohesion < 1.5 OR RelationalCohesion > 4.0
// As classes inside an jar should be strongly related, 
// the cohesion should be high. On the other hand, a value which is too high may 
// indicate over-coupling. A good range for RelationalCohesion is 1.5 to 4.0.
 

Examples of naming constraints

 
 WARN IF Count > 0 IN SELECT TOP 10 TYPES WHERE 
  !NameLike "^[A-Z][a-zA-Z0-9]" AND 
  !IsNested AND 
  !IsGeneratedByCompiler AND
  !IsInTierJar 
//Type name should begin with an Upper character

 WARN IF Count > 0 IN SELECT TOP 10 TYPES WHERE 
  !NameLike "^[A-Z][a-zA-Z0-9]*$" AND 
  IsStatic AND 
  !IsGeneratedByCompiler AND
  !IsFinal AND
  !IsInTierJar 
// static, non-final fields
 
 WARN IF Count > 0 IN SELECT TOP 10 TYPES WHERE 
  IsAbstract AND 
  IsClass AND
  DepthOfInheritance == 1 AND // equivalent to:   DepthOfDeriveFrom "java.lang.Object" == 1
  !NameLike "^Abstract.*$|^.*Factory$" AND
  !IsInTierJar 
//Abstract base class should be prefixed by Abstract or end with Factory
 
WARN IF Count > 0 IN SELECT TOP 10 METHODS WHERE 
 !NameLike "^[a-z]" AND 
 !(IsClassConstructor OR IsConstructor) AND !IsGeneratedByCompiler AND !IsInTierJar
//Methods name should begin with an Lower character
 
WARN IF Count > 0 IN SELECT TOP 10 PACKAGES  WHERE 
 !NameLike "^[a-z]+(\.[a-zA-Z_][a-zA-Z0-9_]*)*$" AND !IsInTierJar 
// Package name 
 
WARN IF Count > 0 IN SELECT TYPES WHERE IsExceptionClass AND !NameLike "Exception$" 
// The name of an exception class should end with 'Exception'
 

Examples of design constraints

WARN IF Count > 0 IN SELECT TOP 10 TYPES WHERE 
  SizeOfInst ==0 AND 
  NbInterfacesImplemented == 0 AND // To be accurate, this constraint doesn't take 
                                   // account of types that implement some interfaces.
  !IsStatic AND 
  !IsGeneratedByCompiler  AND 
  !IsInterface 
// It indicates stateless types that might eventually be turned into static classes.
 
WARN IF Count > 0 IN SELECT TOP 10 TYPES WHERE DepthOfInheritance >= 6 ORDER BY DepthOfInheritance DESC 
// Branches too long in the derivation should be avoided.
  
h2.Examples of encapsulation constraints 
 
WARN IF Count > 0 IN SELECT TYPES WHERE IsNested AND (IsPublic OR IsProtected)
// A nested type should not be public or internal.
 
WARN IF Count > 0 IN SELECT TYPES OUT OF PACKAGES "com.acme.foo" WHERE DepthOfIsUsing "com.acme.foo.Bar" == 1
// Restrict the possibility of using the type "com.acme.foo.Bar" only to certain package.
 
WARN IF Count > 0 IN SELECT METHODS OUT OF PACKAGES "com.acme.foo" WHERE 
DepthOfIsUsing  "com.acme.foo.Bar.doSomething(String)"== 1
// Restrict the possibility of calling the method "com.acme.foo.Bar.doSomething(String)" 
// only to certain package.
 

WARN IF Count > 0 IN SELECT METHODS OUT OF PACKAGES "com.acme.foo"
WHERE DepthOfCreateA "com.acme.foo.Bar" == 1 ORDER BY DepthOfCreateA 
// Restrict the possibility of creating an instance of "com.acme.foo.Bar" only to certain packages.
 
WARN IF Count > 1 IN SELECT PACKAGES OUT OF JARS "AcmeFooBar"
WHERE DepthOfIsUsing "com.acme.foo.Bar" == 1
// Restrict the possibility of using a package only to one jar.
 
WARN IF Count > 0 IN SELECT METHODS OUT OF PACKAGES "com.acme.foo" WHERE 
DepthOfIsUsing "com.acme.foo.Bar.myType" == 1
// Restrict the possibility of using the field 
// "com.acme.foo.Bar.myType" 
// only to certain package.

Examples of queries on the graph of dependencies

SELECT METHODS WHERE IsUsing "com.acme.foo.Bar.Bar()" ORDER BY DepthOfIsUsing 
// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful
// to understand who calls statically who for example to anticipate future impacts 
// of some refactoring or to provide some customized encapsulation constraints.
 
SELECT METHODS WHERE DepthOfIsUsing "com.acme.foo.Bar" <=3
// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful
// to understand who calls statically who for example to anticipate future impacts 
// of some refactoring or to provide some customized encapsulation constraints.
 
SELECT METHODS WHERE 
IsUsedBy "com.acme.foo.Bar"
ORDER BY DepthOfIsUsedBy
// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful
// to understand who calls statically who for example to anticipate future impacts 
// of some refactoring or to provide some customized encapsulation constraints.
 
SELECT METHODS WHERE CreateA "com.acme.foo.Bar" ORDER BY DepthOfCreateA 
// 'CreateA'/'DepthOfCreateA' conditions can be useful to enforce some constraints on design patterns such as factory
// where the ctors must be called only from certain methods or certain type.
 
SELECT METHODS WHERE DepthOfCreateA "com.acme.foo.Bar" < 10 ORDER BY DepthOfCreateA 
// 'CreateA'/'DepthOfCreateA' conditions can be useful to enforce some constraints on design patterns such as factory
// where the ctors must be called only from certain methods or certain type.
 
SELECT METHODS WHERE IsUsing "com.acme.foo.Bar.doSomething(String)" 
 
SELECT METHODS WHERE IsUsing  "com.acme.foo.Bar.doSomething(String)" 
                  OR IsUsedBy "com.acme.foo.Bar.doSomething(String)"
// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful
// to understand who calls statically who for example to anticipate future impacts 
// of some refactoring or to provide some customized encapsulation constraints.
 
SELECT TYPES WHERE DepthOfIsUsedBy "com.acme.foo.Bar" > 2 ORDER BY DepthOfIsUsedBy
// Try to play with the numeric intellisense by selecting the 2 and moving the trackbar.
// A 'IsUsing/IsUsed' relation between two types A and B is created by XDepend as soon as
// there is a 'IsCalled/IsUsedBy' relation between a method of A and a method of B.
 
SELECT PACKAGES WHERE DepthOfIsUsedBy "com.acme.foo.Bar" <=2
// Try to play with the numeric intellisense by selecting the 2 and moving the trackbar.
// A 'IsUsing/IsUsed' relation between two packages A and B is created by XDepend as soon as
// there is a 'IsUsing/IsUsed' relation between a type of A and a type of B.

 
SELECT TYPES WHERE DepthOfDeriveFrom "java.lang.Object" == 1 
// Select classes which derive directly from Object.

SELECT TYPES WHERE NbChildren > 5 ORDER BY NbChildren DESC

Examples of queries to get extremum

SELECT TOP 10 METHODS WHERE !IsConstructor AND !IsClassConstructor ORDER BY NbBCInstructions DESC
// Try to play with the numeric intellisense by selecting the 2 and moving the trackbar.
 
SELECT TOP 10 TYPES FROM JARS "rt" ORDER BY NbMethods DESC
// illustrate the 'FROM' domain of search definition.
 
SELECT TOP 10 METHODS OUT OF PACKAGES "java.lang" ORDER BY NbVariables  DESC
// illustrate the 'OUT OF' domain of search definition.
 
SELECT TOP 10  METHODS ORDER BY NbParameters ,NbVariables ASC, NbBCInstructions DESC
// illustrate the fact that several 'ORDER BY' clause can be specified.
// By default the 'ASC' option is chosen.
// Check in the Query Result panel that 4 columns are displayed.
 
SELECT TOP 10 TYPES ORDER BY  TypeCa DESC
// TypeCa: Afferent Coupling 
// The Afferent Coupling for a particular type is the number of types that depends directly on it.
 
SELECT TOP 10 TYPES ORDER BY  TypeCe DESC
// TypeCe: Efferent Coupling 
// The Efferent Coupling for a particular type is the number of types it directly depends on..
 
SELECT TOP 10 METHODS WHERE !IsConstructor AND !IsClassConstructor ORDER BY NbParameters DESC
 
SELECT TOP 10 TYPES WHERE IsClass ORDER BY NbBCInstructions DESC
 
SELECT TOP 10 TYPES WHERE IsClass ORDER BY NbFields DESC
 
SELECT TOP 10 TYPES WHERE IsClass ORDER BY SizeOfInst DESC

SELECT TOP 10 PACKAGES ORDER BY NbBCInstructions DESC
 
SELECT TOP 10 JARS ORDER BY NbBCInstructions DESC
 
SELECT JARS ORDER BY NbBCInstructions DESC

CQL queries elements

SELECT METHODS

The SELECT METHODS expression allows to select all kind of methods. You can use a combination of following conditions to select some particular methods:
[NameLike] [NameIs] [FullNameIs]
NbBCInstructions NbMethods NbParameters NbVariables BCCyclomaticComplexity
IsUsing DepthOfIsUsing IsDirectlyUsing IsUsedBy DepthOfIsUsedBy IsDirectlyUsedBy CreateA DepthOfCreateA
IsPublic IsProtected IsProtected IsProtectedOrInternal IsProtectedAndInternal IsPrivate IsConstructor IsPropertySetter IsPropertyGetter IsStatic IsVirtual IsAbstract IsUsingBoxing IsUsingUnboxing IsGeneric IsUsingPointers IsOperator IsEventAdder IsEventRemover IsClassConstructor

SELECT FIELDS

SELECT FIELDS expression allows to select all kind of fields. You can use a combination of following conditions to select some particular field:
[NameLike] [NameIs] [FullNameIs]
NbFields SizeOfInst
IsOfType
IsPublic IsProtected IsProtected IsProtectedOrInternal IsProtectedAndInternal IsPrivate IsEnumValue IsStatic IsLiteral IsInitOnly IsEventDelegateObject
IsUsedBy DepthOfIsUsedBy IsDirectlyUsedBy

SELECT TYPES

SELECT TYPES expression allows to select all kind of types. You can use a combination of following conditions to select some particular types:
[NameLike] [NameIs] [FullNameIs]
NbBCInstructions NbMethods NbFields NbTypes BCCyclomaticComplexity SizeOfInst DepthOfInheritance NbChildren TypeCe TypeCa ABT [LCOM] [LCOMHS]
IsUsing DepthOfIsUsing IsDirectlyUsing IsUsedBy DepthOfIsUsedBy IsDirectlyUsedBy DeriveFrom DepthOfDeriveFrom Implement
IsPublic IsProtected IsProtected IsProtectedOrInternal IsProtectedAndInternal IsPrivate IsStatic IsAbstract IsUsingBoxing IsUsingUnboxing IsGeneric IsUsingPointers IsClass IsStructure IsEnumeration IsInterface IsFinal IsNested IsDelegate IsAnnotationClass IsExceptionClass

SELECT PACKAGES

The SELECT PACKAGES expression allows to select some packages. You can use a combination of following conditions to select some particular packages:
[NameLike] [NameIs] [FullNameIs]
NbBCInstructions NbMethods NbFields NbTypes NbPackages
IsUsing DepthOfIsUsing IsDirectlyUsing IsUsedBy DepthOfIsUsedBy IsDirectlyUsedBy

SELECT JARS

The SELECT JARS expression allows to select some jars. You can use a combination of following conditions to select some particular jars:
[NameLike] [NameIs] [FullNameIs]
NbBCInstructions NbMethods NbFields NbTypes NbPackages Abstracness Instability [NormDistFromMainSeq] DistFromMainSeq RelationalCohesion JarCa JarCe
IsUsing DepthOfIsUsing IsDirectlyUsing IsUsedBy DepthOfIsUsedBy IsDirectlyUsedBy

WARN IF xxx IN: Query vs. Constraint

You can transform every CQL query into a CQL constraint by adding a [WARN IF xxx IN] expression at the beginning. There are two kinds of CQL constraint.

• The [Count] constraint which allows you to be warned if the number of matched code elements satisfy a certain numerical condition.
  For example:

  WARN IF Count > 2 IN SELECT METHODS WHERE NbBCInstructions > 200
   
  WARN IF Count <= 40 IN SELECT TYPES WHERE IsExceptionClass
  

• The [Percentage] constraint which allows you to be warned if the percentage of matched code elements satisfy a certain numerical condition. The percentage is computed relatively to the [Domain of search]. For example:

WARN IF Percentage > 5 IN SELECT METHODS WHERE IsUsingBoxing
 
WARN IF Percentage <= 10 IN SELECT TYPES FROM JARS "rt" WHERE IsStatic
 
[WARN IF xxx IN|#_WARN_IF_xxx_IN:_Query_vs._Constrain] expressions are optional.

TOP xxx: Restrict the number of rows in the result

You can restrict the number of code elements selected thanks to a [TOP xxx] expression. For example:

 
SELECT TOP 10 METHODS ORDER BY NbBCInstructions DESC
 
SELECT TOP 10 TYPES WHERE IsClass ORDER BY SizeOfInst DESC

It is likely that queries which contain a [TOP xxx] expression also take advantage of an [ORDER BY xxx] expression.

[TOP xxx] expressions are optional.

FROM / OUT OF xxx: Domain of search

You can restrict the domain of search for code elements by using a [FROM / OUT OF xxx] expression. By default, the domain of search is the whole set of application jars.

A [FROM / OUT OF xxx] expression can be defined as a set of jars, packages or types when the kind of code elements requested is METHODS or FIELDS. For example:

  
SELECT METHODS FROM JARS "rt" WHERE IsAbstract  
 
SELECT FIELDS OUT OF PACKAGES "java.lang","java.io" WHERE IsInitOnly
 
SELECT METHODS OUT OF TYPES "java.lang.String" WHERE CreateA "java.lang.String"

A [FROM / OUT OF xxx] expression can be defined as a set of jars or packages when the kind of code elements requested is TYPES. For example:

  
SELECT TYPES OUT OF PACKAGES "java.lang" WHERE IsUsing "java.lang.String"

A [FROM / OUT OF xxx] expression can be defined as a set of jars when the kind of code elements requested is PACKAGES. For example:

  
SELECT PACKAGES OUT OF JARS "rt" WHERE DepthOfIsUsing "java.util.AbstractList" == 2

The [FROM / OUT OF xxx] feature is not available when the kind of code elements requested is JARS.

[FROM / OUT OF xxx] expressions are optional.

WHERE xxx: Define a set of conditions

You can define a set of condition thanks to:

• The AND and OR binary operators.
• The parenthesis *( ) * operator which allows to fix the order of priority.
• The ! unary operator which allows to do a logical not on a condition.

For example:

  
SELECT METHODS WHERE 
     (  NbBCInstructions > 200 OR 
        BCCyclomaticComplexity > 50 OR 
        NbParameters > 5 OR 
        NbVariables > 8 ) 
     AND 
     !( NameLike "InitializeComponent" OR NameLike "Generated") 
 

[WHERE xxx] expressions are optional but each query must have either a
[WHERE xxx] expression or an [ORDER BY xxx] expression or both.

ORDER BY xxx: Order rows of the result

You can communicate to the CQL runtime engine how to sort code elements selected thanks to the
[ORDER BY xxx] expression. Several metrics can be mentioned. Each metric mentioned can be followed by one of the keyword
[ASC] or [DESC] to precise the order of sort.
The first metric mentioned will be the last one used for sorting. For example:

  
SELECT TYPES ORDER BY NbBCInstructions
 
SELECT METHODS ORDER BY NbBCInstructions, NbParameters DESC, NbVariables ASC
 

[ORDER BY xxx] expressions are optional but each query must have either a
[WHERE xxx] expression or an [ORDER BY xxx]
expression or both.

You can use following metrics to sort your result:
NbBCInstructions NbMethods NbFields NbTypes NbPackages NbParameters NbVariables BCCyclomaticComplexity SizeOfInst DepthOfInheritance NbChildren TypeCe TypeCa ABT [LCOM] [LCOMHS] Abstracness Instability [NormDistFromMainSeq] DistFromMainSeq RelationalCohesion JarCa JarCe DepthOfIsUsing DepthOfIsUsedBy DepthOfCreateA DepthOfDeriveFrom

Comments

You can insert comments

  
SELECT_ METHODS /*Comment 1*/ ORDER 
BY NbBCInstructions // Comment 2
 

Query naming

You can name your queries using the <Name> </Name> tags inside a line of a comment. Query name are then displayed in VisualXDepend in lieu of the whole query and can be more meaningful than the whole query itself:

  
// <Name>Methods too big (NbLinesOfCode)</Name>
WARN IF Count > 0 IN SELECT TOP 10 METHODS WHERE NbLinesOfCode > 30 ORDER BY NbLinesOfCode DESC
 

NameLike

Remarks: The keyword [NameLike] is used to select code elements whose names match a given regular expression.

Example:
Select all fields of application where the name begin with foo

  
SELECT FIELDS WHERE NameLike "^foo" 

NameIs is used to select code elements whose names are equal to a given string.

Example: Select all methods of application where the name is .doSomething(String)

  
SELECT METHODS WHERE NameIs ".doSomething(String)"

FullNameIs

Example: Select all methods of application where the full name is com.acme.foo.Bar.doSomething(String)

  
SELECT METHODS WHERE FullNameIs "com.acme.foo.Bar.doSomething(String)" 

CQL metric conditions

NbLinesOfCode JPTM

Applicable on:* JARS PACKAGES TYPES METHODS
Remarks:

• This metric (known as LOC) is currently computed from ByteCode if code lines are present in ByteCode. Thus it is possible that this count is not exact (for example the return statement will be counted as a line even if it is not present in the source).
  In future release this metric will be computed from source files if found.

Example:

SELECT METHODS WHERE NbLinesOfCode > 20

You can also use the NbBCInstructions keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbLinesOfCode DESC

Recommendations:
METHODS WHERE NbLinesOfCode > 20 are hard to understand and maintain.
METHODS WHERE NbBCInstructions > 40 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).
There is no particular recommendation for NbLinesOfCode values on JARS, PACKAGES and TYPES.

NbBCInstructions JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The number of BC instruction of some code elements might be 0, for example for abstract method, interface or enumeration.

Example:

SELECT METHODS WHERE NbBCInstructions > 200

You can also use the NbBCInstructions keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbBCInstructions DESC

Recommendations:
METHODS WHERE NbBCInstructions > 100 are hard to understand and maintain.
METHODS WHERE NbBCInstructions > 200 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).
There is no particular recommendation for NbBCInstructions values on JARS, PACKAGES and TYPES.

NbLinesOfComment JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: This metric can be computed only if corresponding source files can be found.

Example:

SELECT METHODS WHERE NbLinesOfComment > 10

You can also use the NbLinesOfComment keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbLinesOfComment DESC

PercentageComment JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: This metric is computed with the following formula:
PercentageComment = 100* NbLinesOfComment / (NbLinesOfComment + NbLinesOfCode)

Example:

SELECT METHODS WHERE PercentageComment < 10

You can also use the PercentageComment keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY PercentageComment DESC

NbMethods JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The value of the NbMethods metric is equal to 1 for all methods, no matter it is static or not, it is abstract, it is a constructor, it is a property accessor

Example:

SELECT TYPES WHERE NbMethods > 10

You can also use the NbMethods keyword to order the rows in the result list.

SELECT TOP 10 PACKAGES ORDER BY NbMethods ASC

Recommendations:
TYPES WHERE NbMethods > 20 might be hard to understand and maintain but there might be cases where it is relevant to have a high value for NbMethods. For example, the com.sun.corba.se.impl.logging.ORBUtilSystemException framework class has 1193 methods.
There is no particular recommendation for NbMethods values on JARS and PACKAGES.

NbFields JPTF

Applicable on: JARS PACKAGES TYPES FIELDS

Remarks: The value of the NbFields metric is equal to 1 for all fields, no matter it is static or not, it is an enumeration value, it is literal

SELECT TYPES WHERE NbFields < 10

You can also use the NbFields keyword to order the rows in the result list.

SELECT TOP 10 PACKAGES ORDER BY NbFields ASC

Recommendations:
TYPES WHERE NbFields > 20 AND !IsEnumeration might be hard to understand and maintain but there might be cases where it is relevant to have a high value for NbFields. For example, the sun.security.pkcs11.wrapper.PKCS11Constants class has more than 200 fields. The value of the metric SizeOfInst might be a better indicator to pinpoint complex types.
There is no particular recommendation for NbFields values on JARS and PACKAGES.

NbTypes JPT

Applicable on: JARS PACKAGES TYPES
Remarks: The value of the NbTypes metric is equal to 1 for all types, no matter it is a class, an interface, a nested type...

SELECT JARS WHERE NbTypes > 10

You can also use the NbTypes keyword to order the rows in the result list.

SELECT TOP 10 PACKAGES ORDER BY NbTypes ASC

Recommendations:
There is no particular recommendation for NbTypes values on JARS and PACKAGES.

NbPackages AN

Applicable on: JARS PACKAGES

Remarks: The value of the NbPackages metric is equal to 1 for all packages.

Example:

SELECT JARS WHERE NbPackages == 10

You can also use the NbPackages keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY NbPackages DESC

Recommendations:
There is no particular recommendation for NbPackages values on JARS.

NbInterfacesImplemented T

Applicable on: TYPES

Remarks: The value of the NbInterfacesImplemented metric is equal the number of interfaces implemented by a type.
This metric is available for interfaces, in this case the value is the number of interface extended, directly or indirectly.
For derived class, this metric also count the sum of interfaces implemented by base class(es).

Example:

SELECT TYPES WHERE NbInterfacesImplemented > 3

You can also use the NbInterfacesImplemented keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbInterfacesImplemented DESC

NbParameters M

Applicable on: METHODS

Remarks: The keyword NbParameters is used to define a condition on the number of parameters in METHODS.
Note that the this reference passed as parameters to instance methods in BC is not taken account by the underlying metric.

Example:

SELECT METHODS WHERE NbParameters > 2

You can also use the NbParameters keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY NbParameters DESC

Recommendations:
METHODS WHERE NbParameters > 5 might be painful to call and might degrade performance.
You should prefer using additional properties/fields to the declaring type to handle numerous states.
Another alternative is to provide a class or structure dedicated to handle arguments passing.

NbVariables M

Applicable on: METHODS

Remarks: The keyword NbVariables is used to define a condition on the number of local variables declared in METHODS.

Example:

SELECT METHODS WHERE NbParameters > 2

You can also use the NbVariables keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY NbParameters DESC

Recommendations:
METHODS WHERE NbVariables > 8 are hard to understand and maintain.
METHODS WHERE NbVariables > 15 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).

NbOverloads M

Applicable on: METHODS

Remarks: The keyword NbOverloads is used to define a condition on the number of overloads of a METHODS.
If a method is not overloaded, its NbOverloads value is equals to 1. This metric is also applicable to constructors.

Example:

SELECT METHODS WHERE NbOverloads > 6

You can also use the NbOverloads keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY NbOverloads DESC

Recommendations:
METHODS WHERE NbOverloads > 6 might be a problem to maintain and provoke higher coupling than necessary.
This might also reveal a potential misused of the java support object initialization. This feature helps reducing the number of constructors of a class.

CyclomaticComplexity TM

Applicable on: TYPES METHODS

Remarks: Cyclomatic complexity is a popular procedural software metric equal to the number of decisions that can be taken in a procedure.
Concretely, in java the CC of a method is the number of following expressions found in the body of the method:
if | while | for | case | default | continue | && | || | catch | ternary operator ?: | ??
Following expressions are not counted for CC computation: else | do | switch | try | throws | throw | finally | return | object creation | method call | field access
Adapted to the OO world, this metric is defined both on methods and classes/structures (as the sum of its methods CC).
Notice that the CC of an anonymous method is not counted when computing the CC of its outer method.

Example:

SELECT METHODS WHERE CyclomaticComplexity > 30

You can also use the CyclomaticComplexity keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY CyclomaticComplexity DESC

Recommendations:
Methods where CC is higher than 15 are hard to understand and maintain.
Methods where CC is higher than 30 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).

BCCyclomaticComplexity TM

Applicable on: TYPES METHODS

Remarks: Cyclomatic complexity is a popular procedural software metric equals to the number of decision that can be taken in a procedure (i.e number of if/else, switch/case, ternary operator, loopop yields three ones.

Example:

SELECT METHODS WHERE BCCyclomaticComplexity > 30

You can also use the BCCyclomaticComplexity keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY NbParameters DESC

Recommendations:
METHODS WHERE BCCyclomaticComplexity > 20 are hard to understand and maintain.
METHODS WHERE BCCyclomaticComplexity > 40 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).
There is no particular recommendation for BCCyclomaticComplexity values on TYPES.

BCNestingDepth M

Applicable on: METHODS

Remarks: The metric Nesting Depth for a method is the maximum number of encapsulated scopes inside the body of the method.
The metric BC Nesting Depth is computed from the BC code. Values computed are very similar to what we would expect by computing them from the java source code.

When you have a testing condition with N conditions, such as if( i > 9 && i < 12) then it is considered as N scopes because
it is possible to decompose such conditions into N atomic conditions.

When a method has a large number of case statements corresponding to a switch, the java compiler generally produce optimizations while generating the BC.
In such case, the BC Nesting Depth corresponding value might be slightly higher to what you would expect.

Related Link: A simple trick to code better and to increase testability

Example:

SELECT METHODS WHERE BCNestingDepth > 4

You can also use the BCNestingDepth keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY BCNestingDepth DESC

Recommendations:
METHODS WHERE BCNestingDepth > 4 are hard to understand and maintain.
METHODS WHERE BCNestingDepth > 8 are extremely complex and should be split in smaller methods (except if they are automatically generated by a tool).

SizeOfInst TF

Applicable on: TYPES FIELDS

Remarks: The size of instances of an instance field is defined as the size, in bytes, of instances of its type. The size of instance of a static field is equal to 0. The size of instances of a class or a structure is defined as the sum of size of instances of its fields plus the size of instances of its base class. Fields of reference types (class, interface, delegatez-background-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" lang="EN-GB">SELECT
TYPES WHERE SizeOfInst > 12

You can also use the SizeOfInst keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY SizeOfInst DESC

Recommendations:
TYPES WHERE SizeOfInst > 64 might degrade performance (depending on the number of instances created at runtime) and might be hard to maintain.
However it is not a rule since sometime there is no alternative (the size of instances of the com.sun.java.util.jar.pack.PackageWriter JRE class is 37 Ko).
There is no particular recommendation for SizeOfInst values on FIELDS.

TypeRank T

Applicable on: TYPES
Remarks: TypeRank values are computed by applying the Google PageRank algorithm on the graph of types' dependencies. A homothety of center 0.15 is applied to make it so that the average of TypeRank is 1.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT TYPES WHERE TypeRank > 0.7

You can also use the TypeRank keyword to order the rows in the result list.

SELECT TYPES WHERE TypeRank > 0.7 ORDER BY TypeRank DESC

Recommendations:
Types with high TypeRank should be more carefully tested because bugs in such types will likely be more catastrophic.

MethodRank M

Applicable on: METHODS

Remarks: MethodRank values are computed by applying the Google PageRank algorithm on the graph of methods' dependencies. A homothety of center 0.15 is applied to make it so that the average of MethodRank is 1.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT METHODS WHERE MethodRank > 0.7

You can also use the MethodRank keyword to order the rows in the result list.

SELECT METHODS WHERE MethodRank > 0.7 ORDER BY MethodRank DESC

Recommendations:
Methods with high MethodRank should be more carefully tested because bugs in such methods will likely be more catastrophic.

DepthOfInheritance T

Applicable on: TYPES

Remarks: The depth of inheritance for a class is defined as its number of base classes (including the java.lang.Object class thus depth of inheritance >= 1). The depth of inheritance for an interface is equal to 0.

Example:

SELECT TYPES WHERE DepthOfInheritance > 4

You can also use the DepthOfInheritance keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY DepthOfInheritance DESC

Recommendations:
TYPES WHERE DepthOfInheritance > 6 might be hard to maintain. However it is not a rule since sometime your classes might inherit from tier classes which have a high value for depth of inheritance.

NbChildren T

Applicable on: TYPES

Remarks: The number of children for a class is the number of sub-classes (no matter their positions in the sub branch of the inheritance tree). The number of children for an interface is the number of types that implement it. Types with numerous children are central type.

Example:

SELECT TYPES WHERE NbChildren > 10

You can also use the NbChildren keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbChildren DESC

Recommendations:
There is no particular recommendation for NbChildren values on TYPES.

FieldCa F

Applicable on: FIELDS

Remarks: The Afferent Coupling for a particular field is the number of methods that directly use it.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT FIELDS WHERE FieldCa > 10

You can also use the FieldCa keyword to order the rows in the result list.

SELECT TOP 10 FIELDS ORDER BY FieldCa DESC

Recommendations:
There is no particular recommendation for FieldCa values on FIELDS.

MethodCe M

Applicable on: METHODS

Remarks: The Efferent Coupling for a particular method is the number of methods it directly depends on. Notice that methods declared in framework jars are taken into account.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT METHODS WHERE MethodCe > 10

You can also use the MethodCe keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY MethodCe DESC

Recommendations:
There is no particular recommendation for MethodCe values on METHODS.

MethodCa M

Applicable on: METHODS

Remarks: The Afferent Coupling for a particular method is the number of methods that depends directly on it.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT METHODS WHERE MethodCa > 10

You can also use the MethodCa keyword to order the rows in the result list.

SELECT TOP 10 METHODS ORDER BY MethodCa DESC

Recommendations:
There is no particular recommendation for MethodCa values on METHODS.

TypeCe T

Applicable on: TYPES

Remarks: The efferent coupling for a particular type is the number of types it directly depends on. Types with high efferent coupling are more complex than others but you canineering

Example:

SELECT TYPES WHERE TypeCe > 10

You can also use the TypeCe keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY TypeCe DESC

Recommendations:
There is no particular recommendation for TypeCe values on TYPES.

TypeCa T

Applicable on: TYPES

Remarks: The afferent coupling for a particular type is the number of types that depends directly on it. Types with high afferent coupling are central type. The fact the public class java.security.AccessController holds one of the highest afferent coupling of the JRE is a good indication of the commitment of Java platform on security.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT TYPES WHERE TypeCa > 10

You can also use the TypeCa keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY TypeCa DESC

Recommendations:
There is no particular recommendation for TypeCa values on TYPES.

PackageCe N

Applicable on: PACKAGES

Remarks: The Efferent Coupling for a particular package is the number of packages it directly depends on. Notice that packages declared in framework jars are taken into account.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT PACKAGES WHERE PackageCe > 10

You can also use the PackageCe keyword to order the rows in the result list.

SELECT TOP 10 PACKAGES ORDER BY PackageCe DESC

Recommendations:
There is no particular recommendation for PackageCe values on PACKAGES.

PackageCa N

Applicable on: PACKAGES

Remarks: The Afferent Coupling for a particular package is the number of packages that depends directly on it.

Related Link: Code metrics on Coupling, Dead Code, Design flaws and Re-engineering

Example:

SELECT PACKAGES WHERE PackageCa > 10

You can also use the PackageCa keyword to order the rows in the result list.

SELECT TOP 10 PACKAGES ORDER BY PackageCa DESC

Recommendations:
There is no particular recommendation for PackageCa values on PACKAGES.

ABT T (Association Between Types)

Applicable on: TYPES

Remarks: The Association Between Types metric for a particular class or structure is the number of members of others types it directly uses in the bodies of its methods. Types with high Association Between Types are more complex than others but you 't avoid them.

Example:

SELECT TYPES WHERE ABT > 100

You can also use the ABT keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY ABT DESC

Recommendations:
There is no particular recommendation for ABT values on TYPES.

LCOM T (Lack Of Cohesion Of Methods)

Applicable on: TYPES

Remarks: The single responsibility principle states that a class should have more than one reason to change. Such a class is said to be cohesive. A high [LCOM] value generally pinpoints a poorly cohesive class. There are several [LCOM] metrics. The [LCOM] takes its values in the range [0-1]. The [LCOMHS] (HS stands for Henderson-Sellers) takes its values in the range [0-2]. Note that the [LCOMHS] metric is often considered as more efficient to detect non-cohesive types. A [LCOMHS] value higher than 1 should be considered alarming.

Here are algorithms used by XDepend to compute LCOM metrics:

• LCOM = (1 - sum(MF)/M*F)
• LCOM HS = (M - sum(MF)/F)(M-1)

Where:

• M is the number of methods in class (both static and instance methods are counted, it includes also constructors, properties getters/setters, events add/remove, operator methods).
• F is the number of instance fields in the class.
• MF is the number of methods of the class accessing a particular instance field.
• Sum(MF) ids the sum of MF over all instance fields of the class.

Example:

SELECT TYPES WHERE LCOM > 0.8

You can also use the [LCOM] keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY LCOM DESC

Recommendations:
TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10 might be problematic. However, it is very hard to avoid such non-cohesive types.

LCOMHS T (Lack Of Cohesion Of Methods Henderson-Sellers)

Applicable on: TYPES

Remarks: See the section [LCOM T (Lack Of Cohesion Of Methods)] for the definition of the [LCOMHS] metric.

Example:

SELECT TYPES WHERE LCOMHS > 1.1

You can also use the [LCOMHS] keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY BY LCOMHS DESC

Recommendations:
TYPES WHERE LCOMHS > 1.0 AND NbFields > 10 AND NbMethods >10 should be avoided. Note that this constraint is stronger than the constraint TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10.

JarLevel A

PackageLevel N

TypeLevel T

MethodLevel T

Applicable on: TYPES
Remarks: The Level value for a package is defined as follow:

• Level = 0 : if the package doesn't use any other package.
• Level = 1 : if the package only uses directly package defined in framework jars.
• Level = 1 + (Max Level over package it uses direcly)
• Level = N/A : if the package is involved in a dependency cycle or uses directly or indirectly a package involved in a dependency cycle.

Level metric definitions for jars, types and methods are inferred from the above definition.
This metric has been first defined by John Lakos in his book Large-Scale C++ Software Design.
Related Link: Layering, the Level metric and the Discourse of Method

Example:

SELECT TYPES WHERE TypeLevel == 10

You can also use the JarLevel keyword to order the rows in the result list.

SELECT JARS ORDER BY JarLevel DESC

Recommendations:
This metric helps objectively classify the jars, packages, types and methods as high level,mid level or low level. There is no particular recommendation for high or small values. This metric is also useful to discover dependency cycles in your application. For instance if some packages are matched by the following CQL query, it means that there is some dependency cycles between the packages of your application:

SELECT PACKAGES WHERE !HasLevel AND !IsInTierJar 

Abstractness A

Applicable on: JARS

Remarks: The ratio of the number of internal abstract types (i.e abstract classes and interfaces) to the number of internal types. The range for this metric is 0 to 1, with Abstracness=0 indicating a completely concrete jar and Abstracness=1 indicating a completely abstract jar.

Example:

SELECT JARS WHERE Abstractness  > 0.15

You can also use the Abstracness keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY Abstractness DESC

Recommendations:
JARS.

Instability A

Applicable on: JARS

Remarks: The ratio of efferent coupling (JarCe) to total coupling. Instability = JarCe / (JarCe + JarCa). This metric is an indicator of the package's resilience to change. The range for this metric is 0 to 1, with Instability=0 indicating a completely stable package and Instability=1 indicating a completely instable package.

Example:

SELECT JARS WHERE Instability > 0.15

You can also use the Abstracness keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY Instability DESC

Recommendations:
JARS.

NormDistFromMainSeq A

Applicable on: JARS

Remarks: The perpendicular normalized distance of an jar from the idealized line Abstracness + Instability = 1 (called main sequence). This metric is an indicator of the jar's balance between abstractness and stability. An jar squarely on the main sequence is optimally balanced with respect to its abstractness and stability. Ideal jars are either completely abstract and stable (Instability=0, Abstracness=1) or completely concrete and instable (Instability=1, Abstracness=0). The range for this metric is 0 to 1, with [NormDistFromMainSeq]=0 indicating an jar that is coincident with the main sequence and [NormDistFromMainSeq]=1 indicating an jar that is as far from the main sequence as possible. The picture in the report of XDepend reveals if an jar is in the zone of pain (Instability and Abstracness both close to 0) or in the zone of uselessness (Instability and Abstracness both close to 1).

Example:

SELECT JARS WHERE NormDistFromMainSeq > 0.5

You can also use the [NormDistFromMainSeq] keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY NormDistFromMainSeq DESC

Recommendations:
JARS WHERE NormDistFromMainSeq > 0.7 might be problematic. However, in the real world it is very hard to avoid such jars. Therefore, you should allow a small percentage of your jars to violate this constraint. WARN IF Percentage > 15 IN SELECT JARS WHERE NormDistFromMainSeq > 0.7.

DistFromMainSeq A

Applicable on: JARS

Remarks: The metric DistFromMainSeq is equal to [NormDistFromMainSeq] / Sqrt(2). The range for this metric is thus 0 to 0.7071(-clip: -moz-initial; -moz-background-origin: -moz-initial; -moz-background-inline-policy: -moz-initial;" lang="EN-GB">JARS
WHERE DistFromMainSeq > 0.3

You can also use the DistFromMainSeq keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY DistFromMainSeq DESC

Recommendations:
See [NormDistFromMainSeq] recommendations.

RelationalCohesion A

Applicable on: JARS

Remarks: Average number of internal relationships per type. Let R be the number of type relationships that are internal to this jar (i.e that do not connect to types outside the jar). Let N be the number of types within the jar. RelationalCohesion = (R + 1)/ N. The extra 1 in the formula prevents RelationalCohesion=0 when N=1. The relational cohesion represents the relationship that this jar has to all its types.

Example:

SELECT JARS WHERE RelationalCohesion < 4

You can also use the RelationalCohesion keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY RelationalCohesion DESC

Recommendations:
As classes inside an jar should be strongly related, the cohesion should be high. On the other hand, too high values may indicate over-coupling. A good range for RelationalCohesion is 1.5 to 4.0. JARS WHERE RelationalCohesion < 1.5 OR RelationalCohesion > 4.0 might be problematic.

JarCa A

Applicable on: JARS

Remarks: The number of types outside this jar that depend on types within this jar. High afferent coupling indicates that the concerned jars have many responsibilities.

Example:

SELECT JARS WHERE JarCa > 10

You can also use the JarCa keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY JarCa DESC

Recommendations:
There is no particular recommendation for JarCa values on JARS.

JarCe A

Applicable on: JARS

Remarks: The number of types inside this jar that depends on types outside this jar. High efferent coupling indicates that the concerned jar is dependant.

Example:

SELECT JARS WHERE JarCe > 10

You can also use the JarCe keyword to order the rows in the result list.

SELECT TOP 10 JARS ORDER BY JarCe DESC

Recommendations:
There is no particular recommendation for JarCe values on JARS.

CQL test coverage metrics conditions

Coverage metrics are not available if the metric NbLinesOfCode is not available.

PercentageCoverage JPTM

Applicable on: JARS PACKAGES TYPES METHODS
Remarks: Percentage of code coverage by tests. Code coverage data are imported from coverage files. If you are using the uncoverable attribute feature on a method for example, if all sibling methods are 100% covered, then the parent type will be considered as 100% covered.
Related Link:
Coverage FAQ

Example:

SELECT METHODS WHERE PercentageCoverage < 100

You can also use the PercentageCoverage keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY PercentageCoverage DESC

Recommendations: The closer to 100%, the better.

NbLinesOfCodeCovered JPTM

Applicable on: JARS PACKAGES TYPES METHODS
Remarks: The number of lines of code covered by tests.
Related Link:
Coverage FAQ

Example:

SELECT METHODS WHERE NbLinesOfCodeCovered == 0

You can also use the NbLinesOfCodeCovered keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbLinesOfCodeCovered DESC

NbLinesOfCodeNotCovered JPTM

Applicable on: JARS PACKAGES TYPES METHODS
Remarks: The number of lines of not code covered by tests.
Related Link:
Coverage FAQ

Example:

SELECT METHODS WHERE NbLinesOfCodeNotCovered > 0

You can also use the NbLinesOfCodeNotCovered keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY NbLinesOfCodeNotCovered DESC

PercentageBranchCoverage M

Applicable on: METHODS
Remarks: Branch coverage is a more accurate measure of coverage than PercentageCoveragebecause it compensates for method complexity. Since branch coverage is generated from the underlying opcodes, it often does not map cleanly to source code. That means itB">Coverage FAQ

Example:

SELECT METHODS WHERE PercentageBranchCoverage < 0

You can also use the PercentageBranchCoverage keyword to order the rows in the result list.

SELECT TOP 10 TYPES ORDER BY PercentageBranchCoverage DESC

Recommendations: The bottom line is:
"EN-GB">Use PercentageCoverage as your measure of quality, but
es.

IsExcludedFromCoverage JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The keyword [IsExcludedFromCoverage] is used to define a condition that matches JARS PACKAGES TYPES or METHODS that donoverage data have been gathered because:

• No coverage data is available for the code element or,
• The coverage file is not in-sync with the code or,
• The code element only contains methods that match IsExcludedFromCoverage.

Example:

SELECT METHODS WHERE IsExcludedFromCoverage

CQL code structure conditions

Here are some definitions:

• We consider that a type A uses another type B if at least one method of A is calling one method of B or one method of A is using one field of B.
• We consider that a package A uses another package B if at least one type of A is using one type of B.
• We consider that an jar A uses another jar B if at least one package of A is using one package of B.

Related Links:
-weight: normal; font-size: 7pt; line-height: normal; font-size-adjust: none; font-stretch: normal; -x-system-font: none;"> Keep your code structure clean
on how to componentize existing code

IsUsing JPTM

Enhanced in CQL version 1.1

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The keyword IsUsing is used to select code elements (JARS PACKAGES TYPES METHODS) a particular code element "XXX". The column DepthOfIsUsing "XXX" appears automatically in the table result. A code element which uses directly the code element "XXX" has a DepthOfIsUsing "XXX" value equal to 1. A code element which uses directly a code element which uses directly the code element "XXX" has a DepthOfIsUsing "XXX" value equal to 2 etc...

Since CQL 1.1, the code element referred by the IsUsing clause is not necessarily at the same level as the code elements returned by the query. In the following example the IsUsing clause is referring to a package (java.lang) while the query is returning some methods.

SELECT TYPES WHERE IsUsing "java.lang" ORDER BY DepthOfIsUsing

Example:

SELECT METHODS WHERE IsUsing "java.lang.String.toString()"

SELECT TYPES WHERE IsUsing "java.lang.String"

SELECT PACKAGES WHERE IsUsing "java.lang.String"

SELECT JARS WHERE IsUsing "java.lang.String.String()"

In this context, you can also use the DepthOfIsUsing keyword to order the rows in the result list.

SELECT METHODS WHERE IsUsing "java.lang.String.toString()" BY DepthOfIsUsing

SELECT TYPES WHERE IsUsing "java.lang.String" ORDER BY DepthOfIsUsing

SELECT PACKAGES WHERE IsUsing "java.lang.String" ORDER BY DepthOfIsUsing

SELECT JARS WHERE IsUsing "java.lang.String.String()" ORDER BY DepthOfIsUsing

DepthOfIsUsing JPTM

Enhanced in CQL version 1.1

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: See the section IsUsing JPTM for the definition of the DepthOfIsUsing metric.

Since CQL 1.1, the code element referred by the DepthOfIsUsing clause is not necessarily at the same level as the code elements returned by the query. In the following example the DepthOfIsUsing clause is referring to a package (java.util) while the query is returning some types.

SELECT TYPES WHERE DepthOfIsUsing "java.io" < 3 ORDER BY DepthOfIsUsing

Examples:

SELECT METHODS WHERE DepthOfIsUsing "java.lang.String.toString()" < 3 

SELECT TYPES WHERE DepthOfIsUsing "java.lang.String" < 3

SELECT PACKAGES WHERE DepthOfIsUsing "java.lang" < 3

SELECT JARS WHERE DepthOfIsUsing "java.io" < 3

In this context, you can also use the DepthOfIsUsing keyword to order the rows in the result list.

SELECT METHODS WHERE DepthOfIsUsing "java.lang.String.toString()" < 3 ORDER BY DepthOfIsUsing

SELECT TYPES WHERE DepthOfIsUsing "java.lang.String" < 3 ORDER BY DepthOfIsUsing

SELECT PACKAGES WHERE DepthOfIsUsing "java.lang" < 3 ORDER BY DepthOfIsUsing

SELECT JARS WHERE DepthOfIsUsing "java.io" < 3 ORDER BY DepthOfIsUsing

IsDirectlyUsing JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The keyword IsDirectlyUsing is used to select code elements (JARS PACKAGES TYPES METHODS) which use directly a particular code element LECT METHODS WHERE IsDirectlyUsing "java.lang.String.toString()"

In this context, you can also use the DepthOfIsUsing keyword to order the rows in the result list.

SELECT METHODS WHERE IsDirectlyUsing "java.lang.String.toString()" BY DepthOfIsUsing

IsUsedBy JPTMF

Enhanced in CQL version 1.1

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsUsedBy is used to select code elements (JARS, PACKAGES TYPES METHODS FIELDS) which are directly or indirectly used by a particular code element "XXX". The column DepthOfIsUsedBy "XXX" appears automatically in the table result. The code element "XXX" has a DepthOfIsUsedBy "XXX" value equal to 0. A code element which is used by directly the code element "XXX" has a DepthOfIsUsedBy "XXX" value equal to 1. A code element which is used by directly a code element which is used by directly the code element "XXX" has a DepthOfIsUsedBy "XXX" value equal to 2 etc...

Since CQL 1.1, the code element referred by the IsUsedBy clause is not necessarily at the same level as the code elements returned by the query. In the following example the IsUsedBy clause is referring to a package (java.io) while the query is returning some types

SELECT TYPES WHERE IsUsedBy "java.io"

Examples:

SELECT METHODS WHERE IsUsedBy "java.lang.String.toString()"

SELECT TYPES WHERE IsUsedBy "java.lang.String"

SELECT PACKAGES WHERE IsUsedBy "java.lang"

SELECT JARS WHERE IsUsedBy "java.io"

In this context, you can also use the DepthOfIsUsedBy keyword to order the rows in the result list.

SELECT METHODS WHERE IsUsedBy "java.lang.String.toString()" ORDER BY DepthOfIsUsedBy

SELECT TYPES WHERE IsUsedBy "java.lang.String" ORDER BY DepthOfIsUsedBy

SELECT PACKAGES WHERE IsUsedBy "java.lang" ORDER BY DepthOfIsUsedBy

SELECT JARS WHERE IsUsedBy "java.io" ORDER BY DepthOfIsUsedBy

DepthOfIsUsedBy JPTMF

Enhanced in CQL version 1.1

Applicable on: JARS PACKAGES TYPES FIELDS

Remarks: See the section IsUsedBy JPTMF for the definition of the DepthOfIsUsedBy metric.

Since CQL 1.1, the code element referred by the DepthOfIsUsedBy clause is not necessarily at the same level as the code elements returned by the query. In the following example the DepthOfIsUsedBy clause is referring to a package (java.io) while the query is returning some types.

SELECT TYPES WHERE DepthOfIsUsedBy "java.io" < 3 ORDER BY DepthOfIsUsedBy

Examples:

SELECT METHODS WHERE DepthOfIsUsedBy "java.lang.String.toString()" ORDER BY DepthOfIsUsedBy

SELECT TYPES WHERE DepthOfIsUsedBy "java.lang.String" < 3

SELECT PACKAGES WHERE DepthOfIsUsedBy "java.lang" < 3

SELECT JARS WHERE DepthOfIsUsedBy "java.io" < 3

In this context, you can also use the DepthOfIsUsedBy keyword to order the rows in the result list.

SELECT METHODS WHERE DepthOfIsUsedBy "java.lang.String.toString()" ORDER BY DepthOfIsUsedBy

SELECT TYPES WHERE DepthOfIsUsedBy "java.lang.String" < 3 ORDER BY DepthOfIsUsedBy

SELECT PACKAGES WHERE DepthOfIsUsedBy "java.lang" < 3 ORDER BY DepthOfIsUsedBy

SELECT JARS WHERE DepthOfIsUsedBy "java.io" < 3 ORDER BY DepthOfIsUsedBy

IsDirectlyUsedBy JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsDirectlyUsedBy is used to select code elements (JARS, PACKAGES TYPES METHODS FIELDS) which are directly used by a particular code element "XXX". The column DepthOfIsUsing "XXX" appears automatically in the table result. The clause IsDirectlyUsing "XXX" is equivalent to the clause DepthOfIsUsing "XXX" == 1.

SELECT TYPES WHERE IsDirectlyUsedBy "java.lang.String"

In this context, you can also use the DepthOfIsUsedBy keyword to order the rows in the result list.

 SELECT TYPES WHERE IsDirectlyUsedBy "java.lang.String" ORDER BY DepthOfIsUsedBy

CreateA M

Applicable on: METHODS

Remarks: The keyword CreateA is used to select METHODS which call directly or indirectly a constructor of a particular type "XXX". The column DepthOfCreateA "XXX" appears automatically in the table result. A constructor of the type "XXX" has a DepthOfCreateA "XXX" value equal to 0. A method which calls directly a constructor of "XXX" has a DepthOfCreateA "XXX" value equal to 1. A method which calls directly a method which calls directly a constructor of "XXX" has a DepthOfCreateA "XXX" value equal to 2 etc...
Examples:

 SELECT METHODS WHERE CreateA "java.lang.String"

In this context, you can also use the DepthOfCreateA keyword to order the rows in the result list.

SELECT METHODS WHERE CreateA "java.util.ArrayList" ORDER BY DepthOfCreateA DESC

DepthOfCreateA M

Applicable on: METHODS

Remarks: See the section CreateA M for the definition of the DepthOfCreateA metric.

Example:

SELECT METHODS WHERE DepthOfCreateA "java.util.ArrayList" < 3

In this context, you can also use the DepthOfCreateA keyword to order the rows in the result list.

SELECT METHODS WHERE DepthOfCreateA "java.util.ArrayList" < 3 ORDER BY DepthOfCreateA

DeriveFrom T

Applicable on: TYPES

Remarks: The keyword DeriveFrom is used to select TYPES which derive from directly or indirectly a particular class "XXX". The column DepthOfDeriveFrom "XXX" appears automatically in the table result. The class "XXX" has a DepthOfDeriveFrom "XXX" value equal to 0. A class which derives directly from the class "XXX" has a DepthOfDeriveFrom "XXX" value equal to 1. A class which derives directly from a class which derives directly from the class "XXX" has a DepthOfDeriveFrom "XXX" value equal to 2 etc...

SELECT TYPES WHERE DeriveFrom "java.util.ArrayList"

In this context, you can also use the DepthOfDeriveFrom keyword to order the rows in the result list.

SELECT TYPES WHERE DeriveFrom "java.util.ArrayList" ORDER BY DepthOfDeriveFrom DESC

DepthOfDeriveFrom T

Applicable on: TYPES

Remarks: See the section DeriveFrom T for the definition of the DepthOfDeriveFrom metric.

Example:

SELECT TYPES WHERE DepthOfDeriveFrom "java.util.ArrayList"> 3

In this context, you can also use the DepthOfDeriveFromkeyword to order the rows in the result list.

SELECT TYPES WHERE DepthOfDeriveFrom "java.util.ArrayList"> 3
ORDER BY DepthOfDeriveFrom

Implement T

Applicable on: TYPES

Remarks: The keyword Implement is used to select TYPES which implement or extend a particular interface p>

SELECT TYPES WHERE Implement "java.util.Collection"

HasAnnotation TMF

Applicable on: TYPES METHODS FIELDS
Remarks: The keyword HasAnnotation is used to select TYPES METHODS FIELDS that hosted a particular annotation "XXX".

SELECT METHODS WHERE !IsUsing "org.junit.Assert" AND HasAnnotation "org.junit.Test"

IsOfType F

Applicable on: FIELDS

Remarks: The keyword IsOfType is used to select FIELDS of a particular "XXX".

SELECT FIELDS WHERE IsOfType "java.util.ArrayList"

ReturnType M

Applicable on: METHODS

Remarks: The keyword ReturnType is used to select FIELDS of a particular type "XXX".

SELECT FIELDS WHERE IsOfType "java.util.ArrayList"

CQL boolean conditions

IsPublic TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsPublic is used to define a condition that matches public TYPES, METHODS or FIELDS.

Example:

SELECT METHODS WHERE IsPublic

IsProtected TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsProtected is used to define a condition that matches protected TYPES, METHODS or FIELDS.

Example:

SELECT TYPES WHERE IsProtected

IsProtected TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsProtected is used to define a condition that matches protected TYPES, METHODS or FIELDS. Note that a type can be declared as protected only if it is nested in another type.

Example:

SELECT METHODS WHERE IsProtected

IsPrivate TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsPrivate is used to define a condition that matches private TYPES, METHODS or FIELDS.

Example:

SELECT METHODS WHERE IsPrivate

IsInTierJar NTMF

Applicable on: PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsInTierJar is used to distinguish framework code elements from application code elements.

Example:

SELECT METHODS WHERE IsInTierJar

IsTierJar A

Applicable on: JARS

Remarks: The keyword IsTierJar is used to distinguish framework jars from application jars.

Example:

SELECT JARS WHERE IsTierJar

IsEnumValue F

Not available in RC1 This feature will be available in a future release of XDepend

IsConstructor M

Applicable on: METHODS

Remarks: The keyword IsConstructor is used to define a condition that matches METHODS which are instance constructors.

Example:

SELECT METHODS WHERE IsConstructor

IsPropertySetter M

Applicable on: METHODS

Remarks: The keyword IsPropertySetter is used to define a condition that matches METHODS which are property setters (the method writes a field and is named "set" followed by the name of the written field).

Example:

SELECT METHODS WHERE IsPropertySetter

IsPropertyGetter M

Applicable on: METHODS

Remarks: The keyword IsPropertyGetter is used to define a condition that matches METHODS which are property getters (the method reads a field and is named "get" or "is" followed by the name of the read field).

Example:

SELECT METHODS WHERE IsPropertyGetter

IsStatic TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsStatic is used to define a condition that matches static TYPES, METHODS or FIELDS. A static type is a class which declares only static members.

Example:

SELECT METHODS WHERE IsStatic

IsOverloaded M

Applicable on: METHODS

Remarks: The keyword IsOverloaded is used to define a condition that matches METHODS which are overloaded.

Example:

SELECT METHODS WHERE IsOverloaded

IsAbstract TM

Applicable on: TYPES METHODS

Remarks: The keyword IsAbstract is used to define a condition that matches TYPES or METHODS which are abstract. Note that interfaces and interfacesdding: 0cm;">SELECT TYPES WHERE IsAbstract AND !IsInterface

IsGeneric TM

Not available in RC1 This feature will be available in a future release of XDepend

IsFinalizer M

Applicable on: METHODS

Remarks: The keyword IsFinalizer is used to define a condition that matches METHODS which are finalizer (i.e that override the Object.finalize() method).

Example:

SELECT METHODS WHERE IsFinalizer

HasFinalizer T

Applicable on: TYPES

Remarks: The keyword HasFinalizer is used to define a condition that matches TYPES which define a finalizer.

Example:

SELECT TYPES WHERE HasFinalizer

HasLevel JPTM

Applicable on: TYPES

Remarks: The keyword HasLevel is used to detect dependencies cycle in the structure of your code. More details are available in the recommendation section of the Level metric.

Example:

SELECT PACKAGES WHERE !HasLevel AND !IsInTierJar 

ContainsPackageDependencyCycles A

ContainsTypeDependencyCycles T

ContainsMethodDependencyCycles M

Applicable on: TYPES

Remarks: These keywords allow to know which part of your code contains dependency cycles. Typically, youpace and between methods of a same type (this is recursion). Dependency cycles between jars are detected at the analysis level and are pinpointed in the XDepend HTML report if they exist

Example:

SELECT JARS WHERE ContainsPackageDependencyCycles

IsEntryPoint M

Not available in RC1 This feature will be available in a future release of XDepend

IsInitOnly F

Applicable on: FIELDS

Remarks: The keyword IsInitOnly is used to define a condition that matches FIELDS which are marked as final.

Example:

SELECT FIELDS WHERE IsInitOnly

IsClassConstructor M

Applicable on: METHODS

Remarks: The keyword IsClassConstructor is used to define a condition that matches METHODS which are class constructors (also sometimes referred as static constructors).

Example:

SELECT METHODS WHERE IsClassConstructor

IsClass T

Applicable on: TYPES

Remarks: The keyword IsClass is used to define a condition that matches TYPES which are classes.

Example:

SELECT METHODS WHERE IsClass AND !IsEnumeration

IsEnumeration T

Applicable on: TYPES

Remarks: The keyword IsEnumeration is used to define a condition that matches TYPES which are enumerations.

Example:

SELECT METHODS WHERE IsEnumeration

IsInterface T

Applicable on: TYPES

Remarks: The keyword IsInterface is used to define a condition that matches TYPES which are interfaces.

Example:

SELECT METHODS WHERE IsInterface

IsFinal T

Applicable on: TYPES

Remarks: The keyword IsFinal is used to define a condition that matches TYPES which are sealed. Note that static classes and structures and necessarily marked as sealed.

Related Link: Rambling on the sealed keyword

Example:

SELECT METHODS WHERE IsFinal

IsNested T

Applicable on: TYPES

Remarks: The keyword IsNested is used to define a condition that matches TYPES which are nested.

Example:

SELECT METHODS WHERE IsNested

IsSerializable T

Not available in RC1 This feature will be available in a future release of XDepend

IsAnnotationClass T

Applicable on: TYPES

Remarks: The keyword IsAnnotationClass is used to define a condition that matches TYPES which are annotations.

Example:

SELECT METHODS WHERE IsAnnotationClass

IsExceptionClass T

Applicable on: TYPES

Remarks: The keyword IsExceptionClass is used to define a condition that matches TYPES which are exception classes. An exception class is class which derives directly or indirectly from the class java.lang.Exception, java.lang.Throwable, java.lang.Error.

Example:

SELECT METHODS WHERE IsExceptionClass

IsGeneratedBycompiler TMF

Not available in RC1 This feature will be available in a future release of XDepend

IsDeprecated TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword IsDeprecated is used to define a condition that matches TYPES METHODS and FIELDS which are tagged with the java.lang.Deprecated annotation.

Example:

SELECT METHODS WHERE IsDeprecated

IsSpecialName TMF

Not available in RC1 This feature will be available in a future release of XDepend

CQL boolean conditions dedicated to Build Comparison

Related Link:
Ensure the quality of the code that will be developed this year
How to avoid regression bugs while adding new features

WasAdded JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword WasAdded is used to define a condition that matches JARS PACKAGES TYPES METHODS and FIELDS that were added, i.e that exist in the newer build and not in the older one. This keyword forces the CQL execution to be done against the newer build and is then incompatible with keywords WasRemoved IsNotUsedAnymore IsInOlderBuild.

Example:

SELECT METHODS WHERE WasAdded

WasRemoved JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword WasRemoved is used to define a condition that matches JARS PACKAGES TYPES METHODS and FIELDS that were removed, i.e that exist in the newer build and not in the older one. This keyword forces the CQL execution to be done against the older build and is then incompatible with keywords WasAdded IsUsedRecently and IsInNewerBuild.

Example:

SELECT METHODS WHERE WasRemoved

CodeWasChanged JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The keyword CodeWasChanged is used to define a condition that matches JARS PACKAGES TYPES and METHODS where code were changed. An JARS, a PACKAGES or a TYPES is deemed as changed when it contains at least one method where code was changed or if it contains a child that has been added or deleted.

To know if the code of a method is changed, we compute 2 hash values, one on the BC instruction + name of other members called + string operand and the other one on integer operand. We need the second hash value to avoid setting CodeWasChanged on methods where BC code was just changed because of the modification of an enumeration type. Indeed, in this case the values of the enumeration are directly inserted in the body of the user methods by the compiler.

Example:

SELECT METHODS WHERE CodeWasChanged

CommentsWereChanged JPTM

Applicable on: JARS PACKAGES TYPES METHODS

Remarks: The keyword CommentsWereChanged is used to define a condition that matches JARS PACKAGES TYPES and METHODS that where comments were changed. So far, the algorithm to detect if comments were changed is just based on line number and not on hash values meanings that this algorithm might miss some true positive.

Example:

SELECT METHODS WHERE CommentsWereChanged

VisibilityWasChanged TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword VisibilityWasChanged is used to define a condition that matches TYPES METHODS and FIELDS where visibility was changed.

Example:

SELECT METHODS WHERE VisibilityWasChanged

WasChanged JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword WasChanged is used to define a condition that matches JARS PACKAGES TYPES METHODS and FIELDS that were changed.

• A method is deemed as changed if its ReturnType was changed or its VisibilityWasChanged or its CodeWasChanged.
• A field is deemed as changed if its IsOfType was changed or its VisibilityWasChanged.
• A type is deemed as changed if its VisibilityWasChanged or if its CommentsWereChanged or if it contains a method or a field that WasChanged or WasAdded or WasRemoved.
• A jar is deemed as changed if it contains a type that WasChanged.
• A package is deemed as changed if it contains a jar that WasChanged.

Example:

SELECT METHODS WHERE WasChanged

BecameDeprecated TMF

Not available in RC1 This feature will be available in a future release of XDepend

IsUsedRecently JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsUsedRecently is used to define a condition that matches framework JARS or PACKAGES TYPES METHODS and FIELDS declared in framework jars that were not used by the older build and that are now used by the newer build. This keyword forces the CQL execution to be done against the newer build and is then incompatible with keywords WasRemoved IsNotUsedAnymore IsInOlderBuild.

Example:

SELECT METHODS WHERE IsUsedRecently

IsNotUsedAnymore JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsNotUsedAnymore is used to define a condition that matches JARS or PACKAGES TYPES METHODS and FIELDS declared in framework jars that were used by the older build and that are now not used anymore by the newer build. This keyword forces the CQL execution to be done against the older build and is then incompatible with keywords WasAdded IsUsedRecently and IsInNewerBuild.

Example:

SELECT METHODS WHERE IsNotUsedAnymore

IsUsedDifferently JPT

Applicable on: JARS PACKAGES TYPES

Remarks: The keyword IsUsedDifferently is used to define a condition that matches JARS or PACKAGES and TYPES declared in framework jars that contains some code element (i.e PACKAGES TYPES METHODS or FIELDS) that matches IsNotUsedAnymore or IsUsedRecently.

Example:

SELECT METHODS WHERE IsUsedDifferently

IsInNewerBuild JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsInNewerBuild is used to forces the CQL execution to be done against the newer build. It is then incompatible with keywords WasRemoved IsNotUsedAnymore IsInOlderBuild.

Example:

SELECT METHODS WHERE IsInNewerBuild

IsInOlderBuild JPTMF

Applicable on: JARS PACKAGES TYPES METHODS FIELDS

Remarks: The keyword IsInOlderBuild is used to forces the CQL execution to be done against the older build. It is then incompatible with keywords WasAdded IsUsedRecently and IsInNewerBuild.

Example:

SELECT METHODS WHERE IsInOlderBuild

CQL boolean conditions dedicated to Optimal Encapsulation

Related Link: Optimal Encapsulation

CouldBeProtected TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword CouldBeProtected is used to define a condition that matches public or internal TYPES METHODS and FIELDS that could be declared as protected within the context of the analyzed jars. A code element can be protected if it is not used outside of the classes that derive from the class it is declared in.

Notice that a type declared in the global scope (i.e that is not nested inside a class) cannot be declared as protected.

Example:

SELECT METHODS WHERE CouldBeProtected

CouldBePrivate TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword CouldBePrivate is used to define a condition that matches public or internal TYPES METHODS and FIELDS that could be declared as private within the context of the analyzed jars. A code element can be private if it is not used outside of the type it is declared in.

Notice that a type declared in the global scope (i.e that is not nested inside a class) cannot be declared as private.

Example:

SELECT METHODS WHERE CouldBePrivate

ShouldBePublic TMF

Applicable on: TYPES METHODS FIELDS

Remarks: The keyword ShouldBePublic is used to define a condition that matches internal TYPES METHODS and FIELDS that are used outside their declaring jar. In general, having code elements that are considered as ShouldBePublic is not a problem because it is made on purpose. However, it can be interesting to list them.
Example:

SELECT METHODS WHERE ShouldBePublic

CQL boolean conditions dedicated to Purity / Side-Effects / Mutability

IsImmutable TF

Not available in RC1 This feature will be available in a future release of XDepend

ChangesObjectState M

Applicable on: METHODS

Remarks: The keyword ChangesObjectState is used to define a condition that matches METHODS that explicitly modify an instance field of their type. Notice that constructors are matched. A static method or a class constructor can also be matched, for example, if it modifies the state of an object passed by reference. Notice also that an instance method of a type T that modifies an instance of T that is not the one referenced by the this reference is also matched. The idea is that methods that match ChangesObjectState complexify the program because they break type immutability (see IsImmutable).

Related Link: Immutable types: understand their benefits and use them

Example:

SELECT METHODS WHERE ChangesObjectState

ChangesTypeState M

Applicable on: METHODS

Remarks: The keyword ChangesTypeState is used to define a condition that matches METHODS that explicitly modify an static field of their type. Notice that class constructor, constructors, instance methods and static methods are matched.

Example:

SELECT METHODS WHERE ChangesTypeState

ReadsMutableObjectState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsMutableTypeState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsMutableObjectState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsImmutableObjectState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsMutableObjectState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsImmutableTypeState M

Not available in RC1 This feature will be available in a future release of XDepend

ReadsMutableObjectState M

Not available in RC1 This feature will be available in a future release of XDepend

IsWritingField M

Applicable on: METHODS

Remarks: The keyword IsWritingField is used to select METHODS that write a particular field "XXX", i.e that changes the state of the field "XXX". The keyword IsWritingField matches also methods that indirectly write the field "XXX", i.e that calls a method that writes the field "XXX".

The column DepthOfIsWritingField "XXX" appears automatically in the table result. The methods that directly write the field "XXX" have a DepthOfIsWritingField "XXX" value equal to 0. A method that directly calls a method that directly write the field "XXX" has a DepthOfIsWritingField "XXX" value equal to 1. etc...

An instance constructor that initializes an instance field of its type is not matched.
A static constructor that initializes a static field of its class is not matched.

Example:

SELECT METHODS WHERE IsWritingField "mypackage.MyType.myField"

In this context, you can also use the DepthOfIsWritingField keyword to order the rows in the result list.

SELECT METHODS WHERE IsWritingField "mypackage.MyType.myField" ORDER BY DepthOfIsWritingField DESC

DepthOfIsWritingField M

Applicable on: METHODS

Remarks: See the section IsWritingField for the definition of the DepthOfIsWritingField metric.

Example:

SELECT METHODS WHERE DepthOfIsWritingField "mypackage.MyType.myField" < 3

In this context, you can also use the DepthOfIsWritingField keyword to order the rows in the result list.

SELECT METHODS WHERE DepthOfIsWritingField "mypackage.MyType.myField" < 3 ORDER BY DepthOfIsWritingField DESC

IsDirectlyWritingField M

Applicable on: METHODS

Remarks: The keyword IsDirectlyWritingField is used to select METHODS that write a particular field "XXX", i.e that changes the state of the field "XXX". The clause IsDirectlyWritingField "XXX" is equivalent to the clause DepthOfIsWritingField "XXX" == 0.

Example:

SELECT METHODS WHERE IsDirectlyWritingField "mypackage.MyType.myField"