OTHER RULES

[Contents] [Prev]

11. Other rules.

11.1 Persistency

In order to keep the consistency of the database access, the classes that represent persistent objects (the classes that read/write from/to a database, e.g. Agent) should extend an abstract class PersistentObject. If you feel you need to add read or write functionality to other classes please talk to the System Architect first – you might be looking at the wrong class.

The following protected method are to be overwritten in a class extending PersistentObject: (clear(), read_pick(), write_pick(), read_sql(), write_sql(), delete_pick(), delete_sql()). Don’t overwrite public methods read and write unless you really need it. It if not required to overwrite all of those methods (except method clear) if the functionality is not required for the task at hand. By default a DataException will be thrown if method is not overwritten.

11.2 List selections

All methods that return a list (e.g. Agent.listAgents(), User.listGroupSchemes()), and the class of the data it returns supposed to be derived from class PersistentObject, should return list of keys, not the classes themselves (unless the number of elements is strictly limited).

For example Agent.listAgents() can return a large number of entries, each entry taking a lot of memory - application can run out of memory.

The return type should be String[], or in some cases int[] - this is the safer way as the compiler will check the type of return value.

The standard on method name should start with "list", for example listAgents().

If developer is sure that the number of returned elements is limited the return value can be an array of object of a particular class (e.g. Address[] – when returning list of phone numbers of a particular client). Don’t return ArrayList as in that case the compiler can’t check the type of an object.

11.3 Opening/closing resources

While Java Garbage Collector takes care about memory allocation/deallocation, it does not close immediately other resources for you (e.g. database connections or files). Such resources as database connection or files should be closed immediately when the resources are not needed any more.

If a resource is opened in a method the same method should be responsible for closing it. For example:

This is wrong:

public boolean read_sql(SQL_DATA data, String key) throws DataException
{
  SQL_RS rs = sql_data.select("SELECT * FROM SECURITY WHERE CODE="+
                              sql_data.sql_str(key));
  if (rs.next())
  {
    get_sql_fields(rs);
  }
}
public get_sql_fields(SQL_RS rs)
{
  rs.field("VALUE");
  rs.close();
}

as resource "rs" is closed in a different method – this potentially can course bugs in the future when method read_sql is modified.

The correct way is:

public boolean read_sql(SQL_DATA data, String key) throws DataException
{  
  SQL_RS rs = sql_data.select("SELECT * FROM SECURITY WHERE CODE="+
                              sql_data.sql_str(key));
  if (rs.next())
  {
    get_sql_fields(rs);
  }
  rs.close()
}
public get_sql_fields(SQL_RS rs)
{
  value = rs.field("VALUE");
}

11.4 Class variables access methods

Class variables access methods (or getter and setters) with required access modifier (public or protected) are to be created when access to private class variables required. Do not create getters or setters for the variables that are not supposed to be accessed (e.g. variable "scheme" in class GroupMember is not supposed to be accessed from outside of the class at all and is set in a constructor).

As a standard a getter should not return a reference to the object, but a new object, if the object is not immutable. For example:

public double getRate()
{
  return rate;  // correct
}
public String getName()
{
  return name;  // correct – String is immutable object
}
public DATE getBirthdate()
{
  return birth_date;  // wrong !!! – DATE is not immutable
}
public DATE getBirthdate()
{
  return (DATE)birth_date.clone(); // correct
}

The setters should not assign object reference to a variable if the objects is not immutable:

public void setRate(double value)
{
  rate = value;  // correct
}
public void setName(String value)
{
  name = value; // correct – String is immutable object
}
public void setBirthdate(DATE value)
{
  birth_date = value;  // wrong !!! – DATE is not immutable
}
public void setBirthdate(DATE value)
{
  birth_date.set(value);  // correct
}

Setters should take one parameter only with name value. Normally (but not always) the type of the parameter is the same as a class variable type. Sometimes there can be several setters with different type of value, for example:

public void setSalary(Money value)
{
  salary.set(value);
}
public void setSalary(double value)
{
  salary.set(value);
}

11.5 Servlet-specific rules

Avoid creating new session variables (set by call to a method setAttribute() of the class HttpSession) unless you really can't avoid it, in which case talk to Serguei first or, if he is not available at the time, let him know about the new session variable as soon as possible.

[Contents] [Prev]