001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     bstefanescu
011 */
012package org.nuxeo.ecm.automation.client;
013
014import java.io.IOException;
015import java.util.Map;
016
017import org.nuxeo.ecm.automation.client.model.Blob;
018import org.nuxeo.ecm.automation.client.model.Blobs;
019import org.nuxeo.ecm.automation.client.model.OperationDocumentation;
020
021/**
022 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
023 */
024public interface Session {
025
026    /**
027     * Get the client that created this session.
028     *
029     * @return the client. cannot be null.
030     */
031    AutomationClient getClient();
032
033    /**
034     * Get the login used to authenticate against the server
035     *
036     * @return the login. cannot be null.
037     */
038    LoginInfo getLogin();
039
040    /**
041     * Create a new operation request given an operation ID.
042     *
043     * @param id the ID of the operation to be executed.
044     * @return the operation request
045     */
046    OperationRequest newRequest(String id);
047
048    /**
049     * Create a new operation request given an operation ID and an operation context map.
050     *
051     * @param id the operation id
052     * @param ctx the context map to be used when executing the operation on the server.
053     * @return the operation request
054     */
055    OperationRequest newRequest(String id, Map<String, Object> ctx);
056
057    Object execute(OperationRequest request) throws IOException;
058
059    /**
060     * Get a file from the server given a path identifying the file.
061     *
062     * @param path the file path
063     * @return a blob representation of the file
064     */
065    Blob getFile(String path) throws IOException;
066
067    /**
068     * Get a collection of files from the server given the path identifying the collection.
069     *
070     * @param path the file path
071     * @return a collection of files represented as blobs.
072     */
073    Blobs getFiles(String path) throws IOException;
074
075    OperationDocumentation getOperation(String id);
076
077    Map<String, OperationDocumentation> getOperations();
078
079    /**
080     * Get an adapter of the current session. Adapters can be used to define custom API over a Nuxeo Automation Session.
081     * <p>
082     * Optional operation. Environments that cannot support this method (like GWT) must throw
083     * {@link UnsupportedOperationException}
084     *
085     * @see AutomationClient#getAdapter(Object, Class)
086     */
087    <T> T getAdapter(Class<T> type);
088
089    /**
090     * Get the default schemas that should be sent by the server.
091     * <p>
092     * This is a comma separated String (ex: dublincore,file)
093     * <p>
094     * default value is null (let the server decide what to send)
095     * <p>
096     * when Automation server convert the Documents to JSON, it will use this list to select what properties should be
097     * sent. You can explicitly set the X-NXDocumentProperties header at request level. If defaultSchemas, the request
098     * that don't already have the header set will inherit the default value.
099     *
100     * @since 5.7
101     */
102    String getDefaultSchemas();
103
104    /**
105     * Set the default schemas that should be sent by the server.
106     * <p>
107     * This is a comma separated String (ex: dublincore,file)
108     * <p>
109     * when Automation server convert the Documents to JSON, it will use this list to select what properties should be
110     * sent. You can explicitly set the X-NXDocumentProperties header at request level. If defaultSchemas, the request
111     * that don't already have the header set will inherit the default value.
112     *
113     * @param defaultSchemas list of schemas as a comma separated string
114     * @since 5.7
115     */
116    void setDefaultSchemas(String defaultSchemas);
117
118    /**
119     * Remove any resources held by this session. The session will no more be used again.
120     */
121    void close();
122}