The Principles of Object-oriented Design

Object-oriented design forces software developers to think in terms of objects, rather than procedures. It is based on the following major techniques: inheritance, polymorphism, encapsulation, and modularity. A set of principles are derived from those techniques and can help us have better understanding about object-oriented design.

Single Responsibility Principle 

...

• Do not create omniscient classes that are all-knowing and all-powerful. (E.g., do not write classes which assume behavior of the implementations of other classes.)
• Keep the maximum length of a method as one screen or one or two pages of program listing, no more than about 150 lines;
• Each variable should have a single purpose.

Open Close Principle

...

Program to an Interface

...

Java Programming Paradigms

Enumerated Type

An enumeration is new to Java 5. It is an object type with a finite set of possible values, which is called enum values or enum constants.

...

• Avoid implementing enumerations with public static final int declarations;
• Use enumerated types for readability, maintainability and type safety;
• Use enumerated types as an alternative to boolean variables.

Annotations

Java annotations allow developers to add metadata to source code. The metadata can be utilized by tools at compile time and retained in the compiled Java classes for use at runtime. Annotations should never affect the way a Java program runs, but they may affect the behaviors of a compiler or auxiliary tools. For example, the annotation @SuppressWarnings instructs Java compiler to suppress the specified warning types while the annotation @Transactional in Spring is used to let the application put the calling class or method in a transactional context.

...

Java Language Specification requires annotations are not supposed to “directly affect the semantics of a program”. However, there are few standards that dictate what metadata should be used and carried by annotations, so developers are suggested to use annotations with restraint.

Annotation Examples

Java Generics

Generics were implemented by Java 5 or later. Generics make Java code easier to write and read through making the type of the objects an explicit parameter of the generic code.  Using Generics gives us:

...

• Design methods and classes with generics whenever possible;
• Specify the types of elements in a Java collection whenever it is used;
• Use Enhanced for-loop whenever possible.

Method-Chaining

A few of programming languages and Java applications are promoting the use of method chaining since it is short and simple. The following code snippet is an example of Java method chaining:

...

 Scopes of Variables

Java has three kinds of variables:

...

• Use a variable for a single purpose;
• Keep the life time of variables as short as possible;
• Declare local variables immediately before their use;
• Avoid instance variables if the enclosing object can be accesses by multiple threads concurrently.

Configurability

...

• Avoid hard-coding constants in the business logic;
• Put constants into the central constant classes or properties files unless they have no purpose in any other component of the application;
• Put non-generic business rules in a separate places, rather than mix them with business logics;
• Keep localization (L10N) and internationalization (I18N) in mind.

Services

• All business logic should be placed in stateless services.
• A client should use an aggregate of services, rather than re-implementing the related logic.
• If an existing service is unable and the required functionalities are out of scope of the client, implement them with an additional service class which utilizes existing services.
• A client should have certain liberties to determine what kinds of things would be included in the results of a service.

Application Architecture and Design Patterns

Component-based multi-tier application architectures have been invented and applied for a long time. Those architectures can greatly help us organizing the application components and promoting their reusability by defining layers of responsibilities.

...

Within each layer, there might be one or more design patterns applied to implement corresponding component. Four design patterns will be introduced here.

Business Object/Transfer Object

(Avoid complex business logics, rather than put them into business service)

A business process manages business data and business logic/rules. Business data usually Business Objects is used to separate business data and logic.

Application Service

(Avoid direct external resource access)

Data Access Object

(Database, file system and other external data sources)

Model-View-Controller

Suggestions:

• Each layer has a unique responsibility. Avoid responsibility leaking among layers;

Thread Safety

All web applications are multi-threaded applications. This means that a particular section of code may be accessed at the exact same time by multiple users. As such, you must never store an operation's state in a variable which could be accessed from multiple threads. In the best case, an error will occur when the user's sessions collide. In the worst case, there would be silent data corruption as one user's data is saved over the other's.

This is why all services in the application must be stateless, depending only on their passed parameters.

Getters and Setters

In general, any method in the form of "<some type> get{PropertyName}()" should be a real getter: it should not take any function parameters and it should return the value of a property.  The same with setters - they should return void, take in one parameter, and set the value of the property to that parameter.  If a getter is returning a primitive boolean, then it should be an "is-er" - ie, it should be in the form of "boolean is{PropertyName}()".  These conventions, part of the original JavaBean spec, are well established.  This implies that, for instance, setting the value a member variable in a getter or that a setter which reads from a database are probably preforming behavior which other developers would not expect.  We'd like to try to avoid those kinds of situations.

...

Here, we've got a document which wants to use a BusinessObjectService.  Ideally, we'd like to cache that BusinessObjectService variable in such a way that all instances of the document live in memory can share it - hence we declare the property to be static.  (We also want calls to getBusinessObjectService() running concurrently to not write over the businessObjectService property multiple times - that's why we declare the property to be volatile).  If the businessObjectService property is null, we go ahead and set it from SpringContext, and then we return that property.  This means we're possibly setting the value in the getter.  In this case, though, we find the setting excusable since: a) we know that no other setting of businessObjectService will ever occur; b) we always use getBusinessObjectService(), never the property businessObjectService directly; and c) the setting will only ever occur once.  These constraints make this an unusual case.  In the vast majority of cases, though, getters and setters should truly be getters and setters.

Concrete methods on Interfaces

Java 8 comes with a lot of revolutionary language features.  However, to enable those revolutionary language features, the Java team introduced one ugly feature: the ability to write concrete methods on Interfaces.  The rationale behind this is that in some special cases, a method has a single, standard implementation which should always be used.

...

However, just because the Java language team used this doesn't mean any of the rest of us should.  It's a really strange feature and it should be avoided if at all possible.

Java 8 Streams

Java 8 introduced the concept of a stream that can be filtered, manipulated and collected into a new data type.  These features make code shorter and more readable.  When working with collections, streams should be used when possible in place of code that loops through each element.  Information on Java 8 Streams can be found here: Processing Data with Java SE 8 Streams.

Javadoc/Comment Standards

Javadoc Standards 

The Javadoc standard is a way of writing comments in code that can be used when generating documentation web pages.  These forms of comments should be used for classes and methods when the code warrants a comment.  Comments should be provided to explain why a class exists or why a method is needed.  It should also explain something that is non-obvious in the code.  A comment should not state the obvious (examples "This is the default constructor" or "getter for accountName").

Class Javadocs

• Class javadocs should not have an author tag.
• Constructor javadocs should state anything unique about the constructor like unique build requirements or special setup.

Method Javadocs

• Description of what the method is doing unless it is a getter/setter; however, if getter/setter is doing something other than the standard execution, you should comment.
• Should have at least doclet tags for param, return, and throws.

General Comments about Comments

• We need more comments explaining why things are done the way they are
• Include comments in the code on "why" in any case when "why" isn't readily apparent - for example, extra complexity
• Comment interfaces and abstract classes well as this forms basis for our Service APIs
  • Comment interface and abstract class methods with JavaDoc, including a description of what the method does, why it does it and input parameters, return value, and anticipated exceptions that could be thrown (runtime or checked)
  • Comment on the implementation anything interesting/special/complex about the way the interface is implemented
• JavaDoc comments should be included for all public, protected, and default visibility scopes if a comment is warranted
• Don't comment private with JavaDoc so we don't depend on interfaces that could be refactored
• Code should use descriptive names indicating what and how; comments should explain why
• If the method throws an unchecked exception, it should be manually added to the JavaDoc comments
• Internal method comments should be provided to explain necessary complexity, but not as crutch for poor names or overly complex code
• No "commented out" code should be committed
• If implementing a design pattern, say so in comments
• Bug Fixes
  • Don't include JIRA #s in comments (relate JIRAs to commits via svngit)
  • Don't include specific bug fixes in comments, but keep comments up to date with any code changes
• Do not include @author tags
• No TODO comments in committed code
• Comment any deviation from our coding standards including an explanation for the deviation (non-commented deviations can
  be considered a mistake)
• When refactoring code, any existing comments should be refactored also so the comment matches the current code
• SQL scripts should follow the same comment guidance

Examples

Class Headers

 
/** 
 * This is a description of what this class does... 
 */ 
public class ClassName { ... 

Javadocs for Methods

 
/** 
 * A useful description of what this method does... 
 *
 * @param paramOne This param... 
 * @param paramTwo This param... 
 * @return Returns the... 
 * @throws ExceptionClassName This is thrown when... 
 */ 
public ClassName doMethod(ClassNameOne paramOne, ClassNameTwo paramTwo) throws ExceptionClassName { ... 

...

If your method is in an interface, you Javadocs should follow the standard method format, describing what the method does without describing any implementation details.

Constructor Javadocs

 
/** 
 * This constructor sets up empty instances for the dependent objects... 
 */ 
public ClassName() { ... 

Java Style Guidelines

In general, we are following the recommendations in the book: The Elements of Java Style. Please be familiar with the conventions in that book, as it will result in less reformatting of code later. (Such reformatting makes it harder to detect actual coding changes.)

Configure your Integrated Development Environment to assist you in following the style guidelines: Coding Standards - IDE Settings

Class Structure

For the most part, classes should be laid out in the following order:

• LOG

• fields

• constructors

• overridden methods (public)

• protected/private methods

• getters and setters with logic

• getters/setters with no logic

Use of Braces

In almost all cases, braces should be used when creating blocks. It is too easy to introduce bugs into the system by omitting braces for single-line clauses, especially if-then-else setups. (This is one of those cases where indentation comes into play, if lines after the first are also indented, a developer reading the code might assume that those lines are part of the else clause.

...

This helps save space and is still easy to read. Be sure to have a blank line after a statement like this so it is evident that there are no other statements within the if block.

Naming Conventions

General Java Naming Conventions

In the following table, the naming conventions for Java language entries are listed as well as corresponding examples:

Suggestions:

• All names should be meaningful
• Do remember we are writing code read by not only compilers, but also future developers and implementors
• Keep the names consistent with the domain knowledge or business specifications
• Keep the names consistent across the project-level modules (E.g., name variables which contain a chart code: chartOfAccountsCode)
• Avoid abbrev. (Most IDEs include code completion, which takes away much of the reason for abbreviations.)

General Naming Convention

Naming convention make programs more understandable by making them easier to read. They can also give information about the function of the identifier-for example, whether it's a constant, package,

or class-which can be helpful in understanding the code

Logging

Kuali defaults logging to the INFO level. This means that, in production, any messages at INFO level or higher will go into the application logs. Since this is the primary means of monitoring system operation, we need to be careful to not overload these logs with too much detail, as that tends to obscure any problems which may occur. (It may also cause critical troubleshooting information to be rotated out of the logs too soon.)

...

private static final org.apache.log4j.Logger LOG = org.apache.log4j.Logger.getLogger(BankServiceImpl.class);

Exception Handling

Java defines two kinds of exceptions: checked exceptions and unchecked exceptions.

...

• If you, under normal operation of the system, know that exceptions could occur in the underlying code AND there is some form of reasonable handling which you can do to mitigate the error.
• If the code shouldn't be allowed to continue, which is true in most cases where exceptions get thrown, either don't catch the exception (if it's a RuntimeException), or repackage the exception as a RuntimeException and rethrow it.
  

Multi-catch

• Java 7 introduced a great new feature where, if multiple exceptions are possibly thrown by a single piece of code and if the catch handles each of those exceptions in the very same way, you can simply have one exception handler, like this:

  Code Block
  language java
  try { String.class.newInstance(); } catch (IllegalArgumentException | NoSuchMethodException ex) { // i know these aren't right, but you surely get the use of the language feature now, right? LOG.error(ex); throw new RuntimeException(ex); }

...

• Every exception should be logged. Don’t silently swallow it.
• Don’t discard any exception information, but add more information to an exception. That is, even if you only catch and re-throw, add some of the relevant method parameters or instance variables to the error message.

Method Visibility

Unless child classes really should not be modifying a variable, make all member variables and methods of a class protected. Kuali applications are often extended by implementors and private member variables make that difficult.

Inject All Services

All services used by another service (or any class which is instantiated via Spring) should be injected via the Spring XML files. This forms a kind of documentation as to what services are being used by the service. These service references should be stored in instance variables of the class.

...

 
// this variable is private to ensure that subclasses only use the getter 
private static DataDictionaryService dataDictionaryService; 

// This method is protected. Nothing but this class and subclasses should ever obtain the service reference from here. 
protected DataDictionaryService getDataDictionaryService() { 
    if ( dataDictionaryService == null ) { 
        dataDictionaryService = SpringContext.getBean(DataDictionaryService.class); 
    } 
    return dataDictionaryService; 
} 

Service Injection Exceptions

There are a couple exceptions to this rule.

1. Some services/beans have scope="prototype" in their definition. A new instance of these beans are created every time it is retrieved. These beans should never be cached, as they, in most cases, store session-specific data.
2. KEW, KSB, and KIM services should be obtained upon need. These services maybe accessed from a remote Rice server at some point, so we should not assume we can hold a static reference to a remote service, since such a reference is bound to a particular physical node.
   • However, if the service will be needed more than once within a single web request, hold onto the reference for the life of the method or request so that you do not incur the cost of re-retrieving the service.
   • KIM Exception: the PersonService will always be running locally. It can be injected and/or stored statically.

Do Not Access Services in Static Initializers or Constructors

When classes are instantiated, it can be tempting to initialize service references upon class load or instance creation. Both of these must be avoided. We have no control over when classes are loaded and we do not know when classes may be instantiated. In many cases, these actions take place before the application has completed startup. Accessing the service bus at that time will often result in an error and cause the application startup to fail. (Most business objects and document classes are instantiated during data dictionary validation, so this is a real potential problem. Instead, use the model above to only obtain the service/bean reference upon first demand.

Third-Party Libraries

There are many excellent Java Libraries available which perform operations which are often needed by software applications. Many of the low-level issues we encounter as programmers have already been dealt with, debugged, and used in production applications. We should not re-invent these operations. If you are attempting to perform what seems like a low-level manipulation of data or network operation, please look at the existing libraries in the project, especially the Apache Commons libraries.

Apache Commons libraries

As previously mentioned, the Apache Commons libraries contains classes with a lot of good low-level methods that can be used without developers having to "re-invent the wheel" or use less "safe" alternatives. Here are a couple good examples:

•  Use StringUtils.equals() for String comparison since it is null safe. (NOTE: Since methods like StringUtils.equals() and StringUtils.isNotBlank() are null save, they don’t need to be preceded by an ObjectUtils.isNotNull() check.)
• Use FileUtils.forceMkdir() for creating directories.

Adding New Libraries

All Java libraries delivered with Kuali Project must conform to Open Source licenses in order to avoid legal issues. Before a new third party library is introduced, its license should be submitted and evaluated by the Project. Here is the basic evaluation procedure:

...

• Try to use the existing and well-known Java libraries to increase development productivity;
• Survey its license before introducing a new third party Java library;
• Don’t put a third party Java library into the Project prior to evaluation and approval from the Project.

KFS Constant Classes

One of the General the General Coding Standards for Standards for KFS is "Use constants instead of string literals." A developer might ask, "Where is the best place to put my constant?" There are a variety of contants classes in KFS both global to KFS and specific to individual modules. Put your constant in the most fine-grained location possible that is specific to the type of constant and the module that will be using it. For example, an error key constant used by multiple modules would go in the global org.kuali.kfs.sys.KFSKeyConstants class, while an error key constant that was specific to the PurAP module would go in the org.kuali.kfs.module.purap.PurapKeyConstants class.

Examples of Constant Classes: 

KFS Naming Standards

These are examples of naming convention for KFS documents.

Module Development Standards

...

• A module service interface in the org.kuali.module.integration.<your module code> package that contains all methods that the core financial system and other optional modules need to call. This includes data access methods, business rules, document spawning etc. The implementation for this interface will live in the org.kuali.module.<your module>.service.impl. The corresponding bean should be defined in the org.kuali.module.integration.SpringBeansModules.xmlfile.

  Note
  Module service bean definitions that reside in org.kuali.module.integration.SpringBeansModules.xml cannot reference beans defined in optional module Spring files, e.g. within LaborModuleServiceImpl, other Labor services that are relied on need to be obtained from SpringContext NOT dependency injection.

• Interfaces in the org.kuali.module.integration<your module>.bo package for business objects that the core financial system and other optional modules need to deal with as parameters or return values from your module service methods or reference from their lookups, documents, etc. See Externalizable Business Objects for documentation and the following examples: Account BO's references to ContractsAndGrantsCfda and ContractsAndGrantsAccountAwardInformation and the FP CAB data collection code - look for code references to CapitalAssetInformation and capitalAssetInfo.tag, e.g. refs to CapitalAssetManagementAsset.
  
  
• Public and protected method signatures should not be changed in a non-impacting release. If a method signature change is required, the original method should be deprecated and a new method created. If possible, the original method should call the new method with sensible defaults. 

When one module needs to display information from another module, Externalizable Business Objects should be used. When a module needs to collect additional information for another module, Externalizable Business Objects should be used to determine how to draw the input fields, and the depended on module service should be responsible for the validation (see CapitalAssetInformationValidation). System parameters related to module interfaces should be associated with the depended on module, e.g. CAB parameters related to FP and PURAP collection of CAB data. The data ownership is with CAB, so that is where the parameters belong.

...

In rare cases, we will need to use table(s) as an interface between two optional modules. Those use cases and the specific tables involved were documented on the archived Tabular Inter-Module Interfaces page.

OJB Proxying

• In general we try to set proxy=true on reference and collection descriptors for performance reasons. 
  • In some cases this may require special code, though. And, in other cases it may just not be possible. 
• When auto-update=true, there is often a problem with proxy=true
• Another problem case is when there is a chance the reference can be null, and you are displaying a field of the reference (code is ok since you can use ObjectUtils.isNull); in this case set proxy="false"
• If setting proxy=true doesn't work, explicitly set proxy=false rather than remove the setting altogether; this makes it clear that you didn't just forget the proxy but instead you are purposefully turning it off.

OJB Proxies and testing for nulls

• OJB proxies are sadly resistant to null checks.  This is because a proxy itself may not be null, but until it actually goes to the database to look for a value, it hasn't replaced itself with null yet.  This leads to code examples like this:

  Code Block
  language java
  if (document.getItem() != null) { // document.item is a proxy - it passes the null check because the proxy isn't null return document.getItem().getQuantity() * 2; // but this blows up because when ojb tries to retrieve the item in  // getItem() so it can call getAmount(), it finds there is no item  // in the db and then throws a very strange NullPointerException }

  To help avoid these situations, Rice provides a class org.kuali.rice.krad.util.ObjectUtils (not to be confused with Spring's ObjectUtils or Apache Commons' ObjectUtils) with two methods: isNull() and isNotNull().  These methods force the ORM to check if a proxy is in place and if so, to figure out at that point if the proxy will resolve to null:

  Code Block
  language java
  if (!ObjectUtils.isNull(document.getItem()) { return document.getItem().getQuantity() * 2; // now, if document.getItem() isn't in the database, this whole block of code will be skipped }

  Because of the utility of this method, as well as the fact that it is sometimes difficult to know whether you are dealing with a proxy or not, the KFS product team suggests that you use ObjectUtils.isNull() or ObjectUtils.isNotNull() to perform all null checks.

Static imports / Importing Inner Classes

Static imports (and their cousin - Importing Inner Classes) can be ok in unit test classes, but should be avoided in non-test code. This is to support readability and clarity of code. Consider "CamsConstant.AssetRetirementReasonCode.GIFT" and the following scenarios:

• Unit test that uses this constant repeatedly. The long strings all throughout the file make it tedious to read. A static import alleviates this.
• Long batch class which refers to this constant once. A static import obscures what "GIFT" refers to.

Util classes vs. Services

KFS Currently has several *Util classes typically with static methods. However, Services with public methods on the service interface are preferable to static methods in Util classes, so new code should be placed in public service methods rather than static Util methods.

Using Rice/Client Framework Services

There are a large number of services in the Rice stack. However, not all of them are meant for use by client applications. The vast majority of the services are only used internally by the various modules. The greatest number of services exist in the KEW module. However, only a handful should be used.

...

When there is a choice between a service in the org.kuali.rice or org.kuali.kfs package, prefer the org.kuali.kfs package service.

General Rule for KEW Services

I will list some of the services later, but in general, within the KEW module, if the service returns objects whose names end in "Value", then it is an internal service and should not be used.

Public services in KEW all return "DTO" objects which are capable of being sent over the Kuali Service Bus.

Useful KNS Services

save( businessObject ) 
findByPrimaryKey( class, primaryKeyMap ) 
findBySingleFieldPrimaryKey( class, primaryKeyValue ) 
findMatching( criteriaMap ) 
countMatching( criteriaMap )

findCollectionBySearch( class, criteriaMap )

sendMessage( MailMessage )

getCurrentDate() 
getCurrentSqlDate()

Class getMaintainableClass(String docTypeName) 
String getDocumentTypeName(Class businessObjectClass) 
Class getBusinessObjectClass(String docTypeName)

Document getNewDocument(String documentTypeName) 
boolean documentExists(String documentHeaderId) 
Document getByDocumentHeaderId(String documentHeaderId) 
Document saveDocument(Document document) 
routeDocument(...) 
approveDocument(...) 
sendAdHocRequests(...)

String getPropertyValueString(String key)
boolean getPropertyValueAsBoolean(String key)

parameterExists(...) 
getParameterValueAsBoolean(...) 
getParameterValueAsString(...) 
getParameterValuesAsString(...) 

Public KEW Services

In general, the services below should only be used if there is not a KNS "wrapper" service for the same operation. Often, the KNS services perform additional actions on the document before calling into the workflow engine.

Public KIM Services

getPrincipalByEmployeeId()

getPrincipalByPrincipalName()

getRole()

getRoleByNamespaceCodeAndName()

isAuthorizedByTemplate()

findPermissionsByTemplate()

getPersonByPrincipalName()