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