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