Using the Java Client Libraries
Ensure the following are in the classpath then run your java application:
- TrimClient.jar
- commons-codec-1.6.jar
- commons-logging-1.1.3.jar
- gson-2.2.2.jar
- httpclient-4.3.6.jar
- httpclient-cache-4.3.6.jar
- httpcore-4.3.3.jar
- httpmime-4.3.6.jar
You can get the TrimClient.jat either by building this project or by using the TrimClient.jar included in the TrimServiceSamples\lib folder.
Request / Response model
In almost all the examples below the same pattern is used, a request is composed and a response is expected. The models page assists in pairing a request with the appropriate response class.
A Simple Console Application
The following code fetches the first page of Records using the 'all' search.
import com.hp.TrimClient.*;
import org.apache.http.auth.NTCredentials;
import com.hp.TrimClient.MainObjects.Record;
import com.hp.TrimClient.MainObjectCollections.Records;
import com.hp.TrimClient.MainObjectCollections.RecordsResponse;
import com.hp.TrimClient.Enums.PropertyIds;
public class TrimSample {
private static TrimClient trimClient;
private static void recordSearch() throws Exception {
Records request = new Records();
request.setQ("all");
request.addProperties(PropertyIds.RecordTitle);
RecordsResponse response = trimClient.get(request);
for (Record record : response.getResults()) {
System.out.println( record.getTitle().getValue());
}
}
public static void main(String[] args) throws Exception {
trimClient = new TrimClient("http://192.168.0.12/ServiceAPI",
new NTCredentials("itu_tadmin","XXXXXXX","david-pc", "david-pc"));
recordSearch();
}
}
Fetching User Options
The options that a user has set in the Tools - Options dialog in the HP Records Manager Client are available via the UserOptions Service. This sample demonstrates the Request/Response model at the heart of the ServiceAPI. We:
- first compose a UserOptions Request, then
- GET a UserOptionsResponse using that Request, and lastly
- interrogate the Response
The UserOptions operate a little differently from the MainObject services. Rather than implement a separate end-point for each different type of User Options (as is done with Record, Location, Classification etc) there is a singe base service. This means that the UserOptionsResponse.UserOptions property must be cast to the appropriate user options class.
private static void fetchUserOptions() throws Exception {
TrimUserOptions request = new TrimUserOptions();
request.setUserOptionSetId(UserOptionSetIds.Search);
TrimUserOptionsResponse response = trimClient.get(request);
System.out.println(((SearchUserOptions)response.getUserOptions()).getRecordEditor());
}
Update User Options
User Options may be updated simply by posting a User Options model. The following example changes the Dropzone settings.
private static void updateUserOptions() throws Exception {
DropzoneUserOptions dropzoneOptions = new DropzoneUserOptions();
dropzoneOptions.setOnMinimise(true);
dropzoneOptions.setShowClassifications(true);
TrimUserOptionsResponse response = trimClient.post(dropzoneOptions);
System.out.println(((DropzoneUserOptions)response.getUserOptions()).getOnMinimise());
}
Create a new Record
Main Objects (such as Record or Location) are represented by a main object model. Creating (or modifying) a Main Object is done simply by posting a Main Object model.
NOTE: Main Object types (such as Record and Location) contain a convenience method allowing them to be posted and the underlying object updated, rather than having to use the request / response mode. The two examples below demonstrate these two approaches.
Request / Response
private static void createNewRecord() throws Exception {
RecordType recordType = new RecordType();
recordType.setUri(2);
Record record = new Record();
record.setRecordType(recordType);
record.setTitle("my test Java Record");
RecordsResponse response = trimClient.post(record);
for (Record rec : response.getResults()) {
System.out.println(rec.getTitle());
}
}
Post method
private static void createNewRecord() throws Exception {
RecordType recordType = new RecordType();
recordType.setUri(2);
Record record = new Record(trimClient);
record.setRecordType(recordType);
record.setTitle("My test Java Record");
record.post();
System.out.println(record.getTitle());
}
Create a new Location
The main difference between creating a new Record and any other type of Main Object is knowing which properties are required. These are marked as required in the Help composing service requests. To create a Location ensure that at least TypeOfLocation and name are specified.
private static void createNewLocation() throws Exception {
Location newLocation = new Location(trimClient);
newLocation.setTypeOfLocation(LocationType.Person);
newLocation.setGivenNames("Bob");
newLocation.setSurname("Java Man");
newLocation.addProperties(PropertyIds.LocationSortName);
newLocation.post();
System.out.println(newLocation.getSortName().getValue());
}
Update an existing Main Object
Updating an existing object is the same as creating a new object except that a valid Uri must be sent.
private static void updateRecord() throws Exception {
Record record = new Record(trimClient);
record.setUri(9000000336L);
record.setTitle("A new Title");
record.post();
System.out.println(record.getTitle());
}
Deleting a Main Object
The DeleteMainObject request will delete a main object, it differs from most other requests in that there is no response.
private static void deleteRecord() throws Exception {
DeleteMainObject deleteMainObject = new DeleteMainObject();
deleteMainObject.setId("9000000337");
deleteMainObject.setTrimType(BaseObjectTypes.Record);
trimClient.post(deleteMainObject);
}
Calling Service Actions
Service actions are roughly equivalent to API methods. They are called by adding one or more Actions to a Main Object. The following code makes the new Record a Favorite and sets a user label on the Record.
private static void applyUserLabel() throws Exception {
Record record = new Record(trimClient);
record.setUri(9000000340L);
record.addAction(new SetUserLabel());
SetUserLabel lbl = new SetUserLabel();
UserLabel newLabel = new UserLabel(9000000008L);
lbl.setUserLabelToApply(newLabel);
record.addAction(lbl);
record.addFetchProperties("IsInFavorites", PropertyIds.AttachedLabels);
record.post();
System.out.println(record.getIsInFavorites());
System.out.println(record.getAttachedLabels().getValue());
}
Document Upload
Uploading a document simply requires passing a File object to the post method, this allows the file and the Record metadata to be uploaded together. There are various properties available to modify the upload, including makeNewRevision, keepBookedOut, comments ,CheckinAs. See the web service documentation for Record POST for more details.
Upload and create a new Record
private static void uploadDocument() throws Exception {
Record record = new Record(trimClient);
record.addFetchProperties(PropertyIds.RecordExtension, PropertyIds.RecordTitle);
record.setRecordType(new RecordType(2));
File file = new File((String)null, "mini_stream.jpeg");
record.post(file);
System.out.println(record.getExtension());
}
Upload a new Revision to an existing Record
private static void updateDocument() throws Exception {
Record record = new Record(9000000343L, trimClient);
record.addFetchProperties(PropertyIds.RecordExtension, PropertyIds.RecordTitle);
File file = new File((String)null, "moonshot.jpeg");
record.post(file);
System.out.println(record.getExtension());
}
Attach a file already on the web server
Posting a file over an HTTP connection is not always ideal, especially for large files. You may wish to use some other mechanism to upload the file to the ServiceAPI server and then use the FilePath to tell the Record where to find the file.
private static void uploadFromServer() throws Exception {
Record record = new Record(trimClient);
record.setRecordType(new RecordType(2));
record.setFilePath("slate.jpg");
record.addFetchProperties(PropertyIds.RecordExtension, PropertyIds.RecordTitle);
record.post();
System.out.println(record.getExtension());
}
Set User Defined Field values
Due to their dynamic nature User Defined Fields (UDFs) are handled differently to standard properties. UDFs are sent and received in the Fields property. The Java client implements methods to simplify setting UDF values on an object. The following sample demonstrates using these methods to set a number of different UDF types. The names of UDFs may be found in the Property and Field Definition help (in the Id column).
private static void setCustomFields() throws Exception {
Record record = new Record(trimClient);
record.setUri(9000000346l);
record.setCustomField("PlaceOfInfringement", "Wagga Wagga");
record.setCustomField("PoliceOfficer", new Location(1));
Calendar c = Calendar.getInstance();
c.set(1978, 8, 22);
record.setCustomField("DateOfBirth", c.getTime());
record.post();
System.out.println(record.getFieldValue("PlaceOfInfringement"));
}
Warning: To optimise performance the ServiceAPI caches information concerning User Defined Fields (UDFs) in memory. When a new UDF is added to an object or Record Type you will either need to wait until the IIS Application Pool recycles or trigger an IISReset before the UDF will operate reliably.
Fetching Field values
User Defined Fields (UDFs) may fetched in a very similar way to standard properties. Obviously they are not supported by the PropertyIds enumeration so the string name for the property must be used. These names may be found in the Property and Field Definition help (in the Id column). The following sample shows how to tell the service to fetch certain UDFs and then how to read both the raw value and the string value of the UDF from the object.
private static void getCustomFields() throws Exception {
Records request = new Records();
request.setQ("uri:9000000346");
request.addFetchProperties("PlaceOfInfringement", "PoliceOfficer", "DateOfBirth");
request.setPropertyValue(PropertyType.Both);
request.setStringDisplayType(StringDisplayType.ViewPane);
RecordsResponse response = trimClient.get(request);
for (Record record : response.getResults()) {
System.out.println(record.getFieldValueAsString("PlaceOfInfringement"));
System.out.println(record.getFieldValue("PlaceOfInfringement"));
System.out.println(record.getFieldValueAsString("PoliceOfficer"));
System.out.println(((Location)record.getFieldValue("PoliceOfficer")).getUri());
System.out.println(record.getFieldValueAsString("DateOfBirth"));
Calendar c = Calendar.getInstance();
c.setTime(((TrimDateTime) record.getFieldValue("DateOfBirth")).getDateTime());
System.out.println(c.get(Calendar.YEAR));
}
}