This document gives information about how to use the Java ENS client library to use the web services provided by the Entity Name System.
Class EnsClient
Download...[Builder] Create a new EnsClient Object
Create a new EnsClient with your credential to use Okkam.
To create a new instance of the class EnsClient you have to pass as input an implementation of the Interface IOkkamCredential (see Interface IOkkamCredential).
The creation of an entity requires the user to be registered. For a description about how to become a registered used of the ENS, follow the procedure at this link: http://register.okkam.org/. The registration process defines a username, a password and a X.509 certificate wrapping these informations. The credentials are necessary to access any secured services.
String username = "usertest"; // THE USER NAME USED TO REGISTER
String password = "changeit"; // THE PASSWORD USED TO REGISTER
String okkamPointer = "http://api.okkam.org/okkam-core/WebServices"; // THE POINTER TO THE ENS SERVICE
String path = c:/myCredentialsFolder; // PATH TO THE FOLDER OF THE SECURITY FOLDER WHERE THE CERTIFICATE IS
try {
MyOkkamCredentials credentials = new MyOkkamCredentials(); // MyOkkamCredentials class is a class implementing IOkkamCredential interface.
credentials.init(username, password, path, okkamPointer);
EnsClient entityManager = new EnsClient(credentials);
} catch (OkkamClientException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
}
If your network setting require a Http Proxy to access the Internet, you need to add the following code before creating the instance of the EnsClient object.
ProxyManager proxyManager = ProxyManager.getInstance();
//setting HTTP proxy without authentication.
proxyManager.setProxyHTTPHost("yourProxyUrl");
proxyManager.setProxyHTTPPort("yourProxyPort");
proxyManager.setProxyRequired(true);
proxyManager.setProxyAuthRequired(false);
//setting HTTP proxy with authentication;
proxyManager.setProxyAuthRequired(true);
proxyManager.setProxyUser(conf.getProxyUser());
proxyManager.setProxyPassword(conf.getProxyPassword());
proxyManager.configureProxy();
[Method] getEntity
Get an Entity object from Okkam
This method accept as input a string with the Okkam ID of the Entity that you want to load. The returned object is an Entity.
Example:
String oid = “myokkamID”;
EnsClient client = new EnsClient(credential);
Entity entity = client.getEntity(oid);
[Method] getAlternativeIds
Get all the alternative ids (such as other URI, social security numbers, etc.) for an Okkam Entity
This is a useful method to know all the other identifiers that Okkam knows about an Entity. You pass as input an Okkam ID and you will get a list of strings that are the alternative ids.
Example:
String oid = “myokkamID”;
EnsClient client = new EnsClient(credential);
List
[Method] getOidsByAlternativeId
Get all the Entities that have an ID (URI, email addresses, etc.) as alternative ID
This is a method that you can use to discover which entities inside Okkam have a specific identifier as alternative ID.
Example:
String altID = “http://www.example.com/id/123”;
EnsClient client = new EnsClient(credential);
List
[Method] findEntity
Search Okkam with its query language
This is the simplest and most used method that the EnsClient provides. You pass a query to the system and Okkam will return a list of the Entities that match better with the input string. It is important to know that Okkam has a specific query language that you can use to write advances queries (see Okkam Community Portal)
Example:
EnsClient client = new EnsClient(credential);
String query = "QUERY {
List
[Method] lockEntity
Lock an Entity: nobody will modify it until you will unlock it (or the session will expires)
With this method you “freeze” an Entity. It is mandatory if you want to touch an Okkam Entity. The result string is a “ticket” (as string) that other methods (e.g. update, delete) will ask you before do anything.
String oid = “myokkamID”;
EnsClient client = new EnsClient(credential);
String ticket = client.lockEntity(oid);
[Method] createNewEntity
Insert into Okkam a new Entity, after that you have validated it, and get its new Okkam ID.
With this method you can create new Entities into Okkam. It is important that you validate the Entity that you want to create because without the certificate that you get with the validateEntity method you cannot create new entities. The result of the process is the Okkam ID of the new Entity.
COMMENT: first of all you have to build an entity object.
//THE ENTITY OBJECT IS THE WRAPPER OF ALL THE ENTITY'S INFORMATION
Entity entity = new Entity();
// ENTITY PROFILE CONTAINS MOST OF THE ENTITY DESCRIPTION
ProfileType profile = new ProfileType();
// CREATE AN ATTRIBUTE SET, CONTAINING ALL THE ATTRIBUTES
AttributesType labelList = new AttributesType();
String semantic_type = "person" // SET THE SEMANTIC TYPE OF THE ENTITY
for(ALL YOUR ATTRIBUTES){
// CREATE A SINGLE ATTRIBUTE OBJECT
AttributeType lab = new AttributeType();
// SET THE VALUE OF THE ATTRIBUTE
lab.setValue("THE VALUE OF THE ATTRIBUTE");
// SET THE VALUE OF THE ATTRIBUTE NAME AS A PROPER QNAME
lab.setName(new QName("NamespaceUri", "THE NAME OF THE ATTRIBUTE"));
// SET THE VALUE OID OF THE ATTRIBUTE, IF ANY
lab.setVeid("VEID OF THE ENTITY");
labelList.getAttributes().add(lab);
}
// CREATE AN ALTERNATIVE IDS SET (IF ANY)
AlternativeIdsType alts = new AlternativeIdsType();
for (ALL YOUR ALTERNATIVE IDS) {
// CREATE A SINGLE ALTERNATIVE ID OBJECT
AlternativeIdType alt = new AlternativeIdType();
// SET THE ALTERNATIVE ID VALUE
alt.setId("YOUR ALTERNATIVE ID");
alts.getAlternativeIds().add(alt);
}
// CREATE AN EQUIVALENT IDS SET (IF ANY)
EquivalentOidsType eq = new EquivalentOidsType();
for (YOUR EQUIVALENT IDS) {
// ADD EQUIVALENT ID AS STRING
eq.getEquivalentOids().add("YOUR EQUIVALENT ID");
}
// CREATE AN EXTERNAL REFERENCE SET (IF ANY)
ReferencesType refs = new ReferencesType();
for (ALL YOUR REFERENCES){
// CREATE AN REFERENCE TYPE OBJECT
ReferenceType ref = new ReferenceType();
// SET THE REFERENCE POINTER (URL)
ref.setPointer("REFERENCE URL");
// SET REFERENCE CATEGORY
ref.setCategory("YOUR REFERENCE CATEGORY");
refs.getReferences().add(ref);
}
if (labelList.getAttributes().size() > 0) {
System.out.println("Adding labels");
profile.setAttributes(labelList);
}
if (e.getSemantic_type() != null && !"".equals(semantic_type)) {
System.out.println("Adding semantic type");
profile.setSemanticType(semantic_type);
}
if (refs.getReferences().size() > 0) {
System.out.println("Adding references");
profile.setReferences(refs);
}
if (alts.getAlternativeIds().size() > 0) {
System.out.println("Adding alternatives");
entity.setAlternativeIds(alts);
}
if (eq != null && eq.getEquivalentOids().size() > 0) {
System.out.println("Adding equivalents");
entity.setEquivalentOids(eq);
}
// ADD PROFILE TO ENTITY OBJECT
entity.setProfile(profile);
COMMENT: Once an object is built as described above, you can validate the entity object. The validation of an entity returns, if everything works fine, an EntityValidationReport.
EntityValidationReport report = null;
try {
report = entityManager.validateEntity(entity, force);
} catch (IllegalArgumentException e) {
e.printStackTrace();
} catch (OkkamClientException e) {
e.printStackTrace();
} catch (org.okkam.core.ws.OkkamCoreException e) {
e.printStackTrace();
}
// IF THE VALIDATION WAS POSITIVE, A VALIDATION CERTIFICATE IS RETURNED
String certificate = report.getCertificate();
if(certificate!=null){
// IF THE CERTIFICATE IS NOT NULL, THE VALIDATION IS POSITIVE AND THE ENTITY CAN BE CREATED
entityManager.createNewEntity(certificate);
} else{
" see validateEntity for more information about how to manage entity validation report."
}
[Method] validateEntity
Validate the quality of an Okkam Entity (quality of the profile, check existing similar profiles, etc).
You need this method to validate the quality of an entity before create or update it. It is important that you validate the entity before try to put the new entity into Okkam, the createEntity Method will ask you the returned ticket of the validation process.
"... see createNewEntity for details about how to build the entity object."
EntityValidationReport report = null;
try {
report = entityManager.validateEntity(entity, force);
} catch (IllegalArgumentException e) {
e.printStackTrace();
} catch (OkkamClientException e) {
e.printStackTrace();
} catch (org.okkam.core.ws.OkkamCoreException e) {
e.printStackTrace();
}
String certificate = report.getCertificate();
if(certificate!=null){
// IF THE CERTIFICATE IS NOT NULL, THE VALIDATION IS POSITIVE AND THE ENTITY CAN BE CREATED OR UPDATE
"... see createNewEntity or UpdateEntity for more information."
} else{
// IF THERE IS NO CERTIFICATE, PROBABLY ITS BECAUSE THERE ARE DUPLICATES
XMLEntityConverter entityConverter = new XMLEntityConverter();
ArrayList<Entity> duplicates = new ArrayList<Entity>();
for (String entityXML : report.getCandidateDuplicates()) {
Entity ent = null;
try {
ent = entityConverter.xmlToEntity(entityXML);
} catch (JAXBException e) {
//manage exception.
}
duplicates.add(ent);
}
//
IF
THERE IS NO CERTIFICATE, PROBABLY THE ENTITY SUBMITTED IS OF BAD QUALITY
EntityQualityReport qualityReport = report.getQualityReport();
for(AttributeQualityReport attrRep :qualityReport .getBadQualityAttributes()) {
// MANAGE THE INDEX OF THE BAD ATTRIBUTE
attrRep.getAttributeIndex();
// MANAGE THE MESSAGE EXPLAINING WHY THE ATTRIBUTE IS BAD
attrRep.getMessage();
//MANAGE THE RULE(S) BROKEN BY THE ATTRIBUTE
attrRep.getBrokenRules();
}
}
[Method] unlockEntity
Unlock an Entity
You need the ID of the Entity that you want to unlock and the ticket that you get with the lockEntity method (see lockEntity method).
String oid = “myokkamID”;
EnsClient client = new EnsClient(credential);
String ticket = client.lockEntity(oid);
// do something…
client.unlockEntity(oid,ticket);
[Method] updateEntity
Update Attributes, References, Semantic Type, etc of an Entity profile
This is another useful method that you can use to update the information related to an Okkam ID. It is similar to the creation process (see createNewEntity method, validation, etc) because you have to provide a certificate that the new updated profile is valid, plus the ticket that guarantee that you have locked the entity before try to touch it.
Entity oldEntity;
// update the entity
String oid = oldEntity.getOid();
Entity upEntity = new Entity();
…
// lock the entity that you want to update
String ticket = client.lockEntity(oid);
// validate
EntityValidationReport report = client.validateEntity(upEntity, ignoreDuplicates);
// check report…
String certificate = report.getCertificate());
client.updateEntity(ticket, certificate);
[Method] deleteEntity {private}
Delete an entity from Okkam
[Method] mergeEntities {private}
Merge two or more profiles into one Entity
[Method] splitEntity {private}
Divide an Entity into two or more peaces.
Interface IOkkamCredential
This is a simple Interface that contains all the information to communicate with Okkam. The four main information that you have to provide are:
- DataFolder: the path to the folder on your computer where you have all the security files that your profile needs (see Okkam Security Proxy on Okkam Community Portal)
- OkkamEndPoint: this information is not mandatory and if you don’t provide it the client will use the default Okkam Node
- Password
- Username
