Dear Friend,

People! They make things so complicated! On bad days it can seem like the only thing more frustrating than people, are the organizations that they have created or for which they work:-). People and their organizations do not fit comfortably into highly structured, logical, organized software systems. Producing software that models people and organizations flexibly and efficiently is a challenge. Designing a general-purpose, reusable component to do so is even more challenging. The problem feels as if it should have a simple solution but I hope this month's issue of The Coad Letter will illustrate just how challenging this area can be ... and in the process, communicate some strategies for using the suggested attributes and operations found in the Peter Coad's four class archetypes.

Have fun

Steve

Stephen Palmer (stephen@thecoadletter.com)
Editor of The Coad Letter: Modeling-and-Design Edition

PS#1 Stephen Palmer works with development teams from all over the world helping them create more robust, extensible, object models that reduce the amount of refactoring and rework required during a project, saving both time and money. For more information see http://www.step-10.com/ObjectModeling

PS#2 Find out how TogetherSoft's new "Accelerator for BEA WebLogic Workshop" (WLW) allows developers to model a project, and create and deploy Web services using WLW, all from within Together ControlCenter. Read more about the benefits of the TogetherSoft Accelerator at http://www.togethersoft.com/developers/integrations/beawlw.jsp?c=205.

Party Time

Two types of party

When modeling in color with UML [Coad], a green class represents a party, place or thing. A party is a legal entity, something or someone that can be sued in a court of law. There are essentially only two different kinds of party that we need to consider. The first kind of party is individual people and the second is organizations (companies, charities, government agencies, schools, churches, etc). An initial object model for parties might look something like figure 1.

Figure 1: Abstract Party class with Person and Organization subclasses

The Party-Place-Thing archetype (figure 2) suggests that objects of its classes are likely to have attributes such as names, addresses, unique identity numbers, and other custom values. For parties, places and things, the unique identity numbers are usually assigned by some agency or process outside the scope of the system being modeled. In the case of parties, the unique identity numbers are usually some sort of national, legal or registered id number.

Figure 2: The Party flavor of the Party-Place-Thing archetype

We need to consider a number of questions when applying the details of an archetype to a specific domain. For each of the attributes listed by the archetype we need to ask:

1. What questions does this attribute enable our objects to answer?
2. What services does this attribute help our objects provide?
3. Is this attribute more than just a single, simple value or something more complex?
4. Do we need to track and remember the changes in this attribute's value for business or legal reasons?

In applying the suggestions to our basic model of parties in figure 1, we also need to ask:

5. Are each of these attributes applicable for Person, Organization or both?
6. Where an attribute is applicable for both Person and Organization, are the attributes similar enough for them to be placed in the Party superclass?

What's in a Name?

Lets consider the name attribute first. Answering questions 1 and 2 is reasonably straightforward. People use names to identify themselves. The name attribute can be used by a party object to answer the question 'Which real world person or organization do you represent?'. Unfortunately, as many of us know all too well, names do not necessarily uniquely identify people. Therefore, name attributes also play an important part in search services that locate possible matching objects given a real world party's name or part of that name. It should comes as no surprise then that the Party-Place-Thing and Description archetypes suggest operations that list sets of Party-Place-Thing objects satisfying various criteria.

How about question 3? Are names more complex than a single, simple string of characters? It would be nice if we could answer no but it is not that easy if we want to build a general-purpose party component.

• Organizations and people usually have a single legally registered name.

  To be legally recognized, a new organization has to register their name and other information with a government agency. People also register a name to receive a birth certificate or as part of gaining residency status in another country. My legally registered name is Stephen Richard Palmer.

• Day-to-day people and organizations often use shortened versions, nicknames, aliases or abbreviations of their registered name.

  I use Steve Palmer or Stephen Palmer instead of Stephen Richard Palmer most of the time. Some people use their second given name in preference to their first name. For example, my co-author on A Practical Guide to Feature-Driven Development [Palmer] is known to friends and colleagues as Mac rather than John [Felsing]. Volkswagen is often called VW. Hewlett Packard are often referred to as HP ... and so on. Many software address books provide a nickname field for this reason but some people use more than one variation of their official name.

• There are common mistakes such as the problem of confusing Stephen and Steven with which I am all too familiar.

• Both people and organizations may have names in a language that uses a radically different character set and may therefore have an English language equivalent.

  Tan Ah Teck is the English equivalent of a Chinese name. In Singapore people often pick and use a traditional English christian name. For example, Ah Teck might be known Jonathan Tan to all his friends and colleagues.

So to handle the most general case, we need to allow for multiple names, indicating which one, if any, is the legally registered name. To add to the complexity...

• a person's name can usually be split into family name and given names, the order and number of which differs depending upon culture.

The family name comes first in Chinese names but last in English names. Also Ah Teck is two words (two Chinese characters) that form a single name. In contrast the Richard part of Stephen Richard Palmer is seldom used. If names are to look natural on computer generated letters, e-mail messages, faxes, etc then the software needs to be aware of these differences. Mr. Stephen or Dear Palmer is not a helpful start to a message that is trying to sell me some product or service for example.

• some people append a number or other indicator that distinguishes them from others of the same name in their family

e.g. John Smith II or John Smith Junior.

• a person's name may be decorated by a title, honorific or string of academic and professional qualifications such as Doctor, Lord, BS, MBCS, etc. Some of these precede the name and others are written after the name depending again upon culture.

So as well as being a multi-valued attribute, a person's name attribute needs a more complex structure than a simple string of characters.

Question 4? Do we need to track and remember the changes in name attributes' values for business or legal reasons? Both organizations and people can change their registered name and so may have one or more previous registered names. If it is important to avoid multiple party objects in a system representing the same person or organization (and it frequently is the case in financial institutions where regulations restrict the amount of credit that can be given to a single party), then the previous names of a person or organization are of interest. The intervals of time during which each previous name was the registered name may also be important when examining past transactions with those parties.

The answer to question 5 is trivial. Both people and organizations have names so the attribute is applicable to both.

Question 6 is a little harder to answer. We have already discussed the way a person's name can be broken down into several parts with the family name appearing in various positions. Organization names do not have this type of complexity. Putting together all the factors we have considered we can draw the diagram in figure 3 and use it as a means to help us try and answer question 6.

Figure 3: A first attempt at a model of party names

Since a particular name can only be registered once (shown by the 0..1 to 1 association between the name registration classes and name classes), we can collapse the pink classes into the green name classes storing the dateRegistered there.

Keeping the registered names in an ordered collection means we can derive the value of the dateSuperceded and no longer need that attribute.

The party to which a name belongs is a common feature of both OrganizationName and PersonName.

We might therefore be tempted to answer question 6 with a model that looks as figure 4. Here, we introduce a PartyName superclass and link it to the Party class. Now the Party class can do most of the name management work and the Person and Organization classes need only ensure the right name subclass is being used for their objects.

Figure 4: Refined model of party names

Further analysis might lead to the alternative shape in figure 5 that reduces the amount of inheritance used. Here a name is stored as a simple string of characters with an optional NameDetails object that, for personal names, identifies which substring is the family name and provides the prefix and suffix used to hold titles, honors, sequence numbers and qualifications. One nice feature about this model shape is that we can add a NameDetails object to a Name object at a later date if the details are not known or not currently important. To do the same in the model in figure 4 leaves three attributes without values and feels clumsier.

Figure 5: Alternative model shape further generalizing the structure of names

However, there is a downside of the model in figure 5. When searching for a party by name, it is highly likely that a user will know whether they are searching for a person or an organization. The persistent storage in figure 4 can be arranged so that either PersonName objects are searched or OrganizationNames. The model in figure 5 makes this potential performance and usability improvement harder to achieve.

Note on notation: Name objects are utterly meaningless without their respective Organization and Person objects so I have introduced a party-detail archetype tag and marked the relationships as composition in figure 4 and 5 to indicate that the Name classes are very much subordinate to the party classes.

Obviously we have are now considering low-level design details. Certainly during the initial building of an overall object model we could content ourselves with indicating the existance of previous names, aliases and search operations as shown in figure 6.

Figure 6: Party archetype with expanded names attribute

Conclusion

We have looked at just one attribute suggested by the Party-Place-Thing archetype.

We have challenged that attribute by asking a series of questions about it's applicability to the domain we are modeling (in this case the most general domain imaginable).

We have seen how a suggested attribute under closer examination can expand into more detailed objects.

We have produced a couple of alternative model shapes to support the name-centric questions and services our classes need to answer and perform. We have briefly discussed some of the pros and cons of both. Working through the trade-offs between different solutions is, after all, what design is all about.

References and notes

[1] Coad, De Luca Lefebvre, Java Modeling in Color with UML, Prentice Hall

[2] Palmer, Felsing, A Practical Guide to Feature-Driven Development, Prentice Hall

[3] John M. Felsing (macfelsing@mindspring.com)