Usage
Users will be able to retrieve content from Tridion, using this library, in the form of Java or Scala objects. To do this, first an instance of org.talares.Talares for Java or org.talares.api.Talares for Scala needs to be created.
Once an instance is available the public API can be reached through it. With this API, objects corresponding to Tridion data types can be retrieved. For more information about these types, refer to the subsection datatypes.
The following examples show how the library is to be used. As an example the Page type is used, but this can be substituted by any other available data type if needed. Not all convenience methods will be available for all data types though.
Example of getting a page by its publication ID and item ID:
Java
Talares talares = new Talares();
F.Promise<Page> pagePromise = talares.getPage(1, 2);Scala
val talares = Talares()
val pageFuture = talares.getPage(1, 2)Example of getting a page by its URL (this is a convenience method that is not available for other types):
Java
// Java 7
Talares talares = new Talares();
F.Promise<List<Page>> pagesPromise = talares.getPage("/page-path");
return pagesPromise.map(new F.Function<List<Page>, Page>() {
@Override
public Page apply(List<Page> pages) {
if (pages.isEmpty()) return null;
else return pages.get(0);
}
});
// Java 8
Talares talares = new Talares();
F.Promise<List<Page>> pagesPromise = talares.getPage("/page-path");
return pagesPromise.map(pages -> pages.isEmpty() ? null : pages.get(0));Scala
val talares = Talares()
val pageOptionFuture = getPage("/page-path") map {
case x :: xs => Some(x)
case _ => None
}NOTE -- Finding a page by its URL comes down to executing a search query. Before a search query is executed it is unknown how many results the query will produce. Therefore a collection is always returned in stead of a single value. It is up to the user to handle this result in a fitting way.
Data types
Below are the data types that are available through this library. Next to them the ID's needed for retrieval are specified.
A number of convenience methods are available for selected data types. To create your own, refer to the Scala OData query DSL section.
| Data type | ID's |
|---|---|
| Binary | Publication ID, Binary ID |
| BinaryContent | Publication ID, Binary ID, Variant ID |
| BinaryVariant | Publication ID, Binary ID |
| Component | Publication ID, Item ID |
| ComponentPresentation | Publication ID, Component ID, Template ID |
| CustomMeta | ID |
| Keyword | Publication ID, ID, Taxonomy ID |
| Page | Publication ID, Item ID |
| PageContent | Publication ID, Page ID |
| Publication | ID |
| Schema | Publication ID, Schema ID |
| StructureGroup | Publication ID, ID |
| Template | Publication ID, Item ID |
Deferred values
Deferred values are data type instances which are not available until a second request is made to the webservice. For instance, all the pages contained within a Publication. These can be retrieved when needed.
As stated, fetching the concrete value of a Deferred implies an additional request that needs to be handled and as such adds latency. If the concrete value is not needed, the Deferred fields are best left unused.
Deferred values can be used to retrieve interconnected sets of data without knowing all ID's of the data types that form these sets. For instance a publication will hold a deferred list of pages belonging to it. These pages, in turn, hold deferred lists of component presentations. This way, all pages and component presentations of a publication are available without knowing their specific ID's.
Example usage:
Java
// Java 7
F.Promise<List<Page>> pagesPromise = publication.getPages();
pagesPromise.map(new F.Function<List<Page>, Page>() {
@Override
public Page apply(List<Page> pages) {
if (pages.isEmpty()) return null;
else return pages.get(0);
}
});
// Java 8
F.Promise<List<Page>> pagesPromise = publication.getPages();
pagesPromise.map(pages -> pages.isEmpty() ? null : pages.get(0));Scala
val publication = ... // get a publication
val pageOptionFuture = publication.pages.value map {
case x :: xs => Some(x)
case _ => None
}NOTE -- The Deferred classes do not have a client facing Java counterpart. Their futures are wrapped in Promises as soon as the value of the Deferred is requested. Therefore they manifest themselves as Promise fields on data types in Java. Everything stated above about Deferred fields on Scala data types is therefore also true of Promise fields of Java data types.
Cleaning up
As Talares uses Akka for it's core functionality, an actor system is instantiated when the library is used. As this is an expensive operation, it is done only once. It is therefore up to the user to shut down the system.
If users are done with the library, because the client application is shutting down or they have all the data they need, the actor system should be shut down. Talares provides the terminate() method for this. It's available through both the Java and Scala API and should be used when appropriate and only when appropriate. Terminating prematurely will render the library useless, not using it at all will have the JVM run indefinitely.
