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