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 

Following this principle usually leads to simpler code which is in turn easier to understand, design, and maintain. This principle can also be applied to a method or even a member variable.  If a class or method looks too big, it likely has too many responsibilities and probably ought to be refactored into additional methods or even additional classes.

Suggestions:

• 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

This principle's guidelines are twofold:

• Keep the class or method from being changed by client developers, which will prevent them from introducing new bugs in the existing code. In order to meet this requirement, the classes or method should perform a single responsibility correctly.
• Design the classes or methods that can be extended to meet new requirements. In order to add new functionality, the client developers can use extending techniques, e.g., adding new subclasses, overriding methods, or reusing existing code through delegation.

Program to an Interface

An interface specifies the behaviors of an object without defining its implementation. The interface can be implemented by one or more classes with different flavors of logics.  In order to increase the reusability of our classes, we want to limit their dependencies on other classes as much as possible. “Program to an interface, not an implementation” is just a powerful and simple way to reduce the dependencies among classes.

The two methods in the following code actually perform the same logic: to get the values from the given key-value pairs. The first method uses the argument of type Map and is able to accept any object of a class implementing the Map interface, for example, EnumMap and TreeMap.  The second method, on the other hand, can only accept an object of HashMap or its subclasses. Obviously, the second method is greatly dependent on HashMap, which is not desired.

 
void retrieveValuesFromMap(Map<String, String> fieldValues); 

void retrievevaluesFromHashMap(HashMap<String, String> fieldValues); 

Suggestions:

• During class design, let each class implement at least one interface;
• If a class you need implements an interface, then write your code against that interface;
• If a called class doesn’t implement any interface, then try to write code against its parent far up in the hierarchy;
• Use dependency injection (Spring) whenever possible.

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.

Prior to Java 5, public static final int declarations were used as enum values. Here is an example:

 
public static final int SPRING = 0; 
public static final int SUMMER = 1; 
public static final int AUTUMN = 2; 
public static final int WINTER = 3; 

double getAverageTemperatureOfSeason(int season); 

The declarations are still open to another integer values, and even invalid values. For example, “5’ can be passed to the method getAverageTemperatureOfSeason(int). Compared to the public static final int declarations, enumerations provide type safety.  In the code below, the four enum values are the only legal parameters for the method getAverageTemperatureOfSeason(Season). If an object of another type is passed in, Java compiler will complain about it.

 
public enum Season { SPRING, SUMMER, AUTUMN, WINTER }; 
  
double getAverageTemperatureOfSeason(Season season);  

Suggestions:

• 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.

Currently, there are a few annotations that are available for Kuali Projects:

• Standard annotations defined in Java, including @Deprecated, @Override, and @SuppressWarnings.
• The annotations provided by Spring Framework, for example, @Cacheable and @Transactional.
• Those defined by KFS, such as @ConfigureContext and @NonTransactional.

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:

• Strong type checking to generic code and issues errors if the code violates type safety. Fixing compile-time errors is easier than fixing runtime errors, which can be difficult to find.
• Code readability (types are far more obvious)
• Cut down on the use of cast and possible run time cast exceptions

Here, we would like to promote the usage of Java generics :

• 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:

 
getAccount().getChartOfAccounts().getFinancialObject().getName(); 

This is very convenient, but comes at a cost. When using this syntax, you have no protection from NullPointerException}}s if a link in the chain does not exist. As such, even though it is a pain, you must check the pieces of the chain in sequence. It is not acceptable to catch the {{NullPointerException, as exceptions should only be used for unanticipated errors, not ones which you could reasonably expect. So the above line would probably have to look something like this:

 
String name = "Unknown Object Code"; 
if ( getAccount() != null 
&& getAccount().getChartOfAccounts() != null 
&& getAccount().getChartOfAccounts().getFinancialObject() != null ) { 
name = getAccount().getChartOfAccounts().getFinancialObject().getName(); 
} 

This works because the Java && operator "short-circuits" the expression if the result is known after a certain point. Java evaluates expressions left-to-right, and knows to terminate as soon as it sees a "false" result.

 Scopes of Variables

Java has three kinds of variables:

• Local variables: are declared within a method body. They are only valid from the line they are declared on until the closing curly brace of the method or code block within which they are declared.
• Instance variables: are declared inside a class body but outside of any method bodies. They can live as long as their enclosing object. Their accessibility can be private, protected, default (package private) or public.
• Class variables: are declared inside a class body but outside of any method bodies as instance variables, but they are static. Their existence is not dependent on the creation of an object. They are available globally from the time the enclosing class is loaded into JVM.

Suggestions:

• 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

The Law above shows that details are difficult to deal with. For a business-oriented application, details can be everything that needs to be changed with time, such as business rules, constants, and prompt text. If the details are not appropriately manipulated, they can be duplicated and mingled with business logics, which makes the application code hard to learn and modify. Whenever changing the code to accommodate new requirements, we run the high risk of breaking it because failing to uncover all details related to the change.

Ideally, an application should be highly configurable -- all details should be declared out of application code, a set of metadata are defined to represent the details, and the code only interacts with the metadata, instead of the details themselves.

Suggestions:

• 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.

An application typically has capabilities to access data sources, apply business logic and generate system views for users. Those capabilities can be provided by three components in three layers:

• Presentation layer: represent users to send requests to the underlying system, and present processed data to the users;
• Business Logic layer: encapsulate the business logic of an application, and provide an entry point for operations on the system as a whole;
• Data Access layer: provides a consistent view of the data to business logic layer, and access to the underlying data sources, such as relational database, XML repositories, and flat files.

The architecture logically divides the entire application functionalities into three components and places them in separate logical layers. In the implementation of an application, an object called business object can be used to glue the three layers together by facilitating uniformed data representation.

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.

There are, of course exceptions.  For instance, KFS has a pattern of using a getter to return services in contexts where Spring cannot inject services - ie, where the service needs to be retrieved from SpringContext directly as there is no other choice about the service's retrieval.  That pattern looks commonly like this:

class ExampleDocument {
    private static volatile BusinessObjectService businessObjectService;

    public BusinessObjectService getBusinessObjectService() {
        if (this.businessObjectService == null) {
            businessObjectService = SpringContext.getBean(BusinessObjectService.class);
        }
        return businessObjectService;
    }
}

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.

Hogwash!  Malarkey!  The real reason this feature was introduced was to make it easy to access Streams from Collections in a way that would retain Java's backwards compatibility, because if backwards compatibility wasn't there, Java programmers would grouse and pout.  The Java designers did give us a fair number of revolutionary features, though, and therefore, we forgive them.

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 svn)
  • 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 implementation class, your Javadocs should follow this format:

 
/** 
 * A useful description of what this method does... how does this implementation class 
 * implement the interface. What technology does it use? Is this the default impl? What's 
 * unique about this implementation of the method? 
 *
 * @see org.kuali.service.SomeInterfaceClass#doMethod(ClassNameOne classNameOne, ClassNameTwo classNameTwo) 
 */ 
public ClassName doMethod(ClassNameOne classNameOne, ClassNameTwo classNameTwo) throws ClassName { ... 

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.)

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.

The only exception would be simple one-line statements which are on the same line as the if statement. The statement and if cause must be simple so the line is not too long to easily read. E.g,:

 
// return false if the passed in argument does not have a value 
if ( StringUtils.isBlank( chartOfAccountsCode ) ) return false; 

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.)

If it's for development purposes, put any logging at DEBUG or TRACE levels. Logging levels can always be increased as needed, even on production servers. But when logging anything which is not a problem, be sure that the only code which executes when the logging will not be displayed is the check itself. That is, don't assemble the message unless you are going to output it.

Remember that in a call like:

LOG.debug( "Checking contents of array: " + Arrays.asList( someArray ) ); 

That Java has to first run the Arrays.asList() method, convert it to a string, build a StringBuilder, append the strings, and re-convert the result into a String. Then, it can pass it to the LOG.debug() method which decides whether to show the result. Instead, use a form like the below, as it skips the assembly of the message unless it knows it will be displaying it. (Yes, the logging level check is done twice, but that is acceptable since it will only be done twice if DEBUG logging is turned on.

if ( LOG.isDebugEnabled() ) { 
	LOG.debug( "Checking contents of array: " + Arrays.asList( someArray ) ); 
} 

If you are only displaying a static string or a single string variable, no extra check is necessary, as no processing has to be done to pass that into the method.

When declaring a Logger:

• declare the Logger based on an implementation class not it's interface
• explicitly specify the class, don't use getClass() when calling getLogger()

For example:

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.

• In general, we want to always use unchecked exceptions. This would be all exceptions which extend from RuntimeException.
• Checked exceptions cause a number of headaches.

An exception should be caught and handled explicitly in the following cases:

• 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:

  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); }

Suggestions:

• 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.

Of course, if the class (such as a document) is not generated by Spring, then the services must be obtained via the SpringContext.getBean() method. However, references to these services should be stored in static class variables and retrieved by code via getter methods like the following. This performs the lookup as late as possible and only if needed as well as prevents excessive service lookups.

 
// 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:

3rd Party Evaluation Process

Suggestions:

• 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 Coding 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

For those modules that are not part of the core financial system, the following should be developed to account for java dependencies

• 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.

  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.

All services / utilities used by more than one optional module will need to reside in org.kuali.kfs.* per the restrictions on cross-optional module code dependencies. When moving these types of things into KFS core, create an RNE jira to document the work as usual.

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:

  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:

  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 writing Rice-based applications, you will generally only access services from the KIM and KEW modules in normal operation. KNS services all belong to the client and can be accessed freely.

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()