001package org.nuxeo.ecm.webengine.samples;
002
003import javax.ws.rs.GET;
004import javax.ws.rs.Path;
005import javax.ws.rs.Produces;
006
007import org.nuxeo.ecm.core.rest.DocumentFactory;
008import org.nuxeo.ecm.webengine.model.WebObject;
009import org.nuxeo.ecm.webengine.model.impl.DefaultObject;
010
011/**
012 * Working with Nuxeo Documents.
013 * <p>
014 * Nuxeo Documents are transparently mapped to WebObjects so that you can easily access your documents through
015 * WebEngine.
016 * <p>
017 * Nuxeo Documents are defined by a document type and can be structured in a hierarchy based on their type. The ancestor
018 * of all document types is the "Document" type.
019 * <p>
020 * Document types are transparently mapped to WebObject types, so that you don't need to explicitly declare WebObjects
021 * that expose documents. By default all documents are exposed as DocumentObject instances (which is an WebObject). If
022 * you need specific control over your document type you need then to explicitly declare a new WebObject using the same
023 * type name as your document type. This way, the default binding to DocumentObject will be replaced with your own
024 * WebObject.
025 * <p>
026 * <b>Note</b> that it is recommended to subclass the DocumentObject when redefining document WebObjects.
027 * <p>
028 * Also, Documents as WebObjects may have a set of facets. Documents facets are transparently exposed as WebObject
029 * facets. When redefining the WebObject used to expose a Document you can add new facets using @WebObject annotation
030 * (these new facets that are not existing at document level but only at WebObject level).
031 * <p>
032 * To work with documents you need first to get a view on the repository. This can be done using the following methods:
033 * <br>
034 * {@code DocumentFactory.getDocumentRoot(ctx, path)} or {@code DocumentFactory.getDocument(ctx, path)} <br>
035 * The difference between the two methods is that the getDocumentRoot is also setting the newly created document
036 * WebObject as the root of the request chain. The document WebObject created using the DocumentFactory helper class
037 * will represent the root of your repository view. To go deeper in the repository tree you can use the
038 * {@code newDocument} methods on the DocumentObject instance.
039 * <p>
040 * <b>Remember</b> that when working with documents you may need to log in to be able to access the repository. (it
041 * depends on whether or not the repository root is accessible to Anonymous user) For this reason we provide in this
042 * example a way to login into the repository. This also demonstrates <b>how to handle errors</b> in WebEngine. The
043 * mechanism is simple: At your module root resource level you redefine a method {@link SamplesRoot}
044 * {@code public Object handleError(WebApplicationException e)} that will be invoked each time an uncatched exception is
045 * thrown during the request. From that method you should return a suitable response to render the error. To ensure
046 * exceptions are correctly redirected to your error handler you must catch all exceptions thrown in your resource
047 * methods and rethrowing them as following: {@code ... } catch (Exception e) { throw WebException.wrap(e); } </code>.
048 * The exception wrapping is automatically converting exceptions to the ones defined by WebEngine model.
049 *
050 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
051 */
052@WebObject(type = "Documents")
053@Produces("text/html;charset=UTF-8")
054public class DocumentsObject extends DefaultObject {
055
056    @GET
057    public Object doGet() {
058        return getView("index");
059    }
060
061    /**
062     * Get a repository view rooted under "/default-domain".
063     */
064    @Path("repository")
065    public Object getRepositoryView() {
066        return DocumentFactory.newDocumentRoot(ctx, "/default-domain");
067    }
068
069}