Model Tutorial

The basic idea of jpim is to provide a library with the Model element of an MVC architecture.

In case of the contact package, the model is fairly complex and has been modeled after the "vCard Mime Directory Profile" (see the specifications for more details).
The idea is a strong typed model (versus a property based implementation), but fairly complete, so many different types of applications can make use of it.

The model itself is only defined as interfaces, that specify the contract with the actual implementation. Best way to understand the different elements, is to take a closer look at the above mentioned vCard MIME Directory Profile.
When creating model instances, it is recommended to use the model factory. At the moment you will only be able to obtain the default factory (the BasicContactModelFactory); however, it is likely that in the future you can state a flavor when obtaining the factory instance:

ContactModelFactory cmf = Pim.getContactModelFactory();

Model instances should be obtained from the respective factory methods e.g.:

Contact contact = cmf.createContact();

The following example will create Contact instance with some data:

Contact contact = cmf.createContact();
contact.addCategory("Business");

//a personal identity
PersonalIdentity pid = cmf.createPersonalIdentity();
pid.setFormattedName("Frank Miller");
pid.setFirstname("Frank");
pid.setLastname("Miller");
contact.setPersonalIdentity(pid);

//an address
Address addr = cmf.createAddress();
addr.setStreet("Somestreet");
addr.setCity("Somecity");
addr.setPostalCode("55555");
addr.setCountry("United States");
addr.setWork(true);
contact.addAddress(addr);

//some communications
Communications comm = cmf.createCommunications();
contact.setCommunications(comm);

//a phone number
PhoneNumber number = cmf.createPhoneNumber();
number.setNumber("+1(55)555-4575");
number.setWork(true);
comm.addPhoneNumber(number);
      
//an email address
EmailAddress email = cmf.createEmailAddress();
email.setAddress("somebody@aol.com");
comm.addEmailAddress(email);

//an organizational identity
OrganizationalIdentity orgid = cmf.createOrganizationalIdentity();
orgid.setRole("Unit Manager");
orgid.setTitle("Boss");

//and the organization     
Organization org = cmf.createOrganization();
org.setURL("http://www.wimpi.net");
org.setName("Wimpi Inc.");
org.addUnit("IT");
org.addUnit("Software Development");
orgid.setOrganization(org);
contact.setOrganizationalIdentity(orgid);

We agree that the expressivity of the model makes it fairly complex. A first thought would be to simplify it, but on the second thought we realize that this is probably not the right way to go (as we want the model to be applicable in many different applications, not some specific one).

However, we are also aware that you would like to save yourself writing more code than necessary, so we thought that the best solution for the problem is the so called Facade pattern. Basically this is an implementation/interface that hides the complexity of the model, being taylored to the needs of a specific application.
If you have a specific need, you probably might need to implement a facade once, however, we consider this worth the work, as you will most likely be able to use other facilities provided by the library (like importing and exporting to vCards for example).

jpim comes with an example facade, the import net.wimpi.pim.contact.facades.SimpleContact class.
The simplest way to see what it does for you is to wrap the Contact instance from above and retrieve data more easily:

SimpleContact sct = new SimpleContact(contact);
String email = sct.getFullEmail();
String company = sct.getCompany()