usage.html

---
layout: main
title: Talares | Usage
---
<article>

  <h1>Usage</h1>
  <hr>

  <p>
    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 <strong>org.talares.Talares</strong> for Java or <strong>org.talares.api.Talares</strong>
    for Scala needs to be created.
  </p>

  <p>
    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
    <a href="#data-types">datatypes</a>.
  </p>

  <p>
    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.
  </p>

  <p>Example of getting a page by its publication ID and item ID:</p>

  <p>Java</p>
{% highlight java %}
Talares talares = new Talares();
F.Promise<Page> pagePromise = talares.getPage(1, 2);
{% endhighlight %}

  <p>Scala</p>
{% highlight scala %}
val talares = Talares()
val pageFuture = talares.getPage(1, 2)
{% endhighlight %}

  <p>Example of getting a page by its URL (this is a convenience method that is not available for other types):</p>

  <p>Java</p>
{% highlight 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));
{% endhighlight %}

  <p>Scala</p>
{% highlight scala %}
val talares = Talares()
val pageOptionFuture = getPage("/page-path") map {
  case x :: xs => Some(x)
  case _ => None
}
{% endhighlight %}

  <p>
    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.
  </p>

  <article id="data-types">

    <h2>Data types</h2>

    <p>
      Below are the data types that are available through this library. Next to them the ID's needed for retrieval are
      specified.
    </p>

    <p>
      A number of convenience methods are available for selected data types. To create your own, refer to the Scala
      <a href="query-dsl.html">OData query DSL</a> section.
    </p>

    <table>
      <thead>
      <tr>
        <th>Data type</th>
        <th>ID's</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>Binary</td>
        <td>Publication ID, Binary ID</td>
      </tr>
      <tr>
        <td>BinaryContent</td>
        <td>Publication ID, Binary ID, Variant ID</td>
      </tr>
      <tr>
        <td>BinaryVariant</td>
        <td>Publication ID, Binary ID</td>
      </tr>
      <tr>
        <td>Component</td>
        <td>Publication ID, Item ID</td>
      </tr>
      <tr>
        <td>ComponentPresentation</td>
        <td>Publication ID, Component ID, Template ID</td>
      </tr>
      <tr>
        <td>CustomMeta</td>
        <td>ID</td>
      </tr>
      <tr>
        <td>Keyword</td>
        <td>Publication ID, ID, Taxonomy ID</td>
      </tr>
      <tr>
        <td>Page</td>
        <td>Publication ID, Item ID</td>
      </tr>
      <tr>
        <td>PageContent</td>
        <td>Publication ID, Page ID</td>
      </tr>
      <tr>
        <td>Publication</td>
        <td>ID</td>
      </tr>
      <tr>
        <td>Schema</td>
        <td>Publication ID, Schema ID</td>
      </tr>
      <tr>
        <td>StructureGroup</td>
        <td>Publication ID, ID</td>
      </tr>
      <tr>
        <td>Template</td>
        <td>Publication ID, Item ID</td>
      </tr>
      </tbody>
    </table>

  </article>

  <article id="deferred-values">

    <h2>Deferred values</h2>

    <p>
      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.
    </p>

    <p>
      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.
    </p>

    <p>
      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.
    </p>

    <p>Example usage:</p>

    <p>Java</p>
{% highlight 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));
{% endhighlight %}

<p>Scala</p>
{% highlight scala %}
val publication = ... // get a publication
val pageOptionFuture = publication.pages.value map {
  case x :: xs => Some(x)
  case _ => None
}
{% endhighlight %}

    <p>
      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.
    </p>

  </article>

  <article id="cleaning-up">

    <h2>Cleaning up</h2>

    <p>
      As Talares uses <a href="http://akka.io/">Akka</a> 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.
    </p>

    <p>
      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 <strong>terminate()</strong> 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.
    </p>

  </article>

</article>