001/*******************************************************************************
002 * Copyright (c) 2017 Red Hat Inc 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 *     Red Hat Inc - initial API and implementation
011 *******************************************************************************/
012package org.eclipse.kapua.gateway.client;
013
014/**
015 * A client connection
016 * <p>
017 * An instance of a client can be obtained by building and instance
018 * via different protocol stacks. e.g. see the {@code KuraMqttProfile}.
019 * </p>
020 * <p>
021 * In order to free resources the instance has to be closed when it is no
022 * longer needed.
023 * </p>
024 * <p>
025 * Data is exchanged by the use of {@link Application}s.
026 * </p>
027 */
028public interface Client extends AutoCloseable {
029
030    public interface Builder {
031
032        public Client build() throws Exception;
033    }
034
035    /**
036     * Get control over the transport
037     * 
038     * @return The transport control instance
039     */
040    public Transport transport();
041
042    /**
043     * Create a new application instance
044     * <p>
045     * This method only returns a new builder which will
046     * create a new instance once {@link Application.Builder#build()} is called.
047     * Before that the application is not built and no resources are claimed.
048     * </p>
049     * <p>
050     * Application IDs are unique. If an application ID is already allocated it
051     * cannot be allocated a second time. The second call to {@link Application.Builder#build()} will fail.
052     * However this application ID only allocated once the call to {@link Application.Builder#build()}
053     * succeeded.
054     * </p>
055     * 
056     * @param applicationId
057     *            The ID of the application to create
058     * @return the new {@link Application.Builder} instance
059     */
060    public Application.Builder buildApplication(String applicationId);
061}