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 *     ataillefer
019 */
020package org.nuxeo.ecm.automation.client;
021
022import java.io.IOException;
023
024import org.nuxeo.ecm.automation.client.jaxrs.spi.RequestInterceptor;
025
026/**
027 * The connection to the automation service is done the first time you create a session. To create a session you need to
028 * pass the authentication information. If null is passed as the user name an anonymous session will be created. Note
029 * that anonymous sessions are not always accepted by a Nuxeo Server (it depends on the server configuration).
030 * <p>
031 * When you attempt to create a new session using the same authentication info as an already created session the session
032 * will be reused (TODO this is optional for implementors?)
033 * <p>
034 * Note for implementors: the implementation should provide a constructor that initialize the base URL
035 *
036 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
037 */
038public interface AutomationClient {
039
040    /**
041     * @since 6.0
042     * @param interceptor
043     */
044    void setRequestInterceptor(RequestInterceptor interceptor);
045
046    /**
047     * Gets the automation service URL.
048     */
049    String getBaseUrl();
050
051    /**
052     * Creates a new session. If no interceptors configured connect anonymously.
053     */
054    Session getSession() throws IOException;
055
056    /**
057     * Create a new session using the given login callback to gather login info. The given callback will be notified
058     * after the session is created.
059     */
060    Session getSession(LoginCallback loginCb) throws IOException;
061
062    /**
063     * Creates a new session using the given login.
064     */
065    Session getSession(String username, String password) throws IOException;
066
067    /**
068     * Creates a new session using the given token.
069     *
070     * @since 5.7
071     */
072    Session getSession(String token) throws IOException;
073
074    /**
075     * Creates a new session using the given token callback by following these steps:
076     * <ul>
077     * <li>Look for a token saved locally using {@link TokenCallback#getLocalToken()}</li>
078     * <li>If it doesn't exist, use {@link TokenCallback#getRemoteToken(java.util.Map))} to acquire a token remotely
079     * using the information gathered by {@link TokenCallback#getTokenParams()}, and save the token locally using
080     * {@link TokenCallback#saveToken(String)}</li>
081     * <li>Get a session with the token using {@link #getSession(String)}</li>
082     * </ul>
083     *
084     * @since 5.7
085     */
086    Session getSession(TokenCallback cb) throws IOException;
087
088    /**
089     * Adapts the given object to the given type. Return the adapter instance if any, otherwise null.
090     * <p>
091     * Optional operation. Framework that doesn't supports reflection like GWT must throw
092     * {@link UnsupportedOperationException}
093     */
094    <T> T getAdapter(Session session, Class<T> adapterType);
095
096    /**
097     * Register an adapter for a given type. Registration is not thread safe. You should register adapters at
098     * initialization time. An adapter type can be bound to a single adaptable type.
099     *
100     * @param typeToAdapt
101     * @param adapterType
102     */
103    // FIXME: this javadoc doesn't correspond to the method signature.
104    void registerAdapter(AdapterFactory<?> factory);
105
106    /**
107     * Marshaller registration for pojo bean
108     *
109     * @since 5.7.2
110     * @param clazz the pojo bean to add to Marshalling
111     */
112    void registerPojoMarshaller(Class clazz);
113
114    /**
115     * Cleanup any resources held by this client. After a shutdown the client is no more usable.
116     */
117    void shutdown();
118
119}