001/*
002 * flattr4j - A Java library for Flattr
003 *
004 * Copyright (C) 2011 Richard "Shred" Körber
005 *   http://flattr4j.shredzone.org
006 *
007 * This program is free software: you can redistribute it and/or modify
008 * it under the terms of the GNU General Public License / GNU Lesser
009 * General Public License as published by the Free Software Foundation,
010 * either version 3 of the License, or (at your option) any later version.
011 *
012 * Licensed under the Apache License, Version 2.0 (the "License");
013 * you may not use this file except in compliance with the License.
014 *
015 * This program is distributed in the hope that it will be useful,
016 * but WITHOUT ANY WARRANTY; without even the implied warranty of
017 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
018 */
019package org.shredzone.flattr4j.connector;
020
021import java.util.Collection;
022
023import org.shredzone.flattr4j.exception.FlattrException;
024import org.shredzone.flattr4j.exception.MarshalException;
025import org.shredzone.flattr4j.oauth.AccessToken;
026import org.shredzone.flattr4j.oauth.ConsumerKey;
027
028/**
029 * Builds and executes a single call against the Flattr API.
030 *
031 * @author Richard "Shred" Körber
032 * @since 2.0
033 */
034public interface Connection {
035
036    /**
037     * Base URL to connect to. This must be an absolute URL.
038     *
039     * @param url
040     *            URL to connect to.
041     * @return this
042     */
043    Connection url(String url);
044
045    /**
046     * Access token to be used for calls that require authentication. If no
047     * {@link AccessToken} is set, the call will be placed anonymously.
048     *
049     * @param token
050     *            {@link AccessToken} to be used
051     * @return this
052     */
053    Connection token(AccessToken token);
054
055    /**
056     * Consumer key to be used. Usually, this is only necessary in the OAuth2
057     * authentication process.
058     *
059     * @param key
060     *            {@link ConsumerKey} to be used
061     * @return this
062     */
063    Connection key(ConsumerKey key);
064
065    /**
066     * Call to be placed against the URL. The call string may contain placeholders that
067     * are prepended by a colon (e.g. "users/:username/things").
068     * <p>
069     * If no call is set, the {@link #url(String)} is invoked unchanged.
070     *
071     * @param call
072     *            Signature of the call to be invoked
073     * @return this
074     */
075    Connection call(String call);
076
077    /**
078     * A parameter to be used for a placeholder in the call string. If the call string
079     * does not contain a matching placeholder, it will be silently ignored.
080     *
081     * @param name
082     *            Parameter name, without colon prepended
083     * @param value
084     *            Value to be used. Will be URL encoded.
085     * @return this
086     */
087    Connection parameter(String name, String value);
088
089    /**
090     * An array of parameters to be used for a placeholder in the call string. If the call
091     * string does not contain a matching placeholder, it will be silently ignored.
092     *
093     * @param name
094     *            Parameter name, without colon prepended
095     * @param value
096     *            Values to be used.
097     * @return this
098     * @since 2.7
099     */
100    Connection parameterArray(String name, String[] value);
101
102    /**
103     * Query parameter to be used in the URL.
104     *
105     * @param name
106     *            Parameter name
107     * @param value
108     *            Parameter value
109     * @return this
110     */
111    Connection query(String name, String value);
112
113    /**
114     * Data to be transported to the call. Requires {@link RequestType#POST} or
115     * {@link RequestType#PATCH}, otherwise an exception will be thrown.
116     *
117     * @param data
118     *            Data to be sent
119     * @return this
120     */
121    Connection data(FlattrObject data);
122
123    /**
124     * Form parameter to be sent. Requires {@link RequestType#POST}, otherwise an
125     * exception will be thrown. Do not mix with {@link #data(FlattrObject)}.
126     *
127     * @param name
128     *            Parameter name
129     * @param value
130     *            Parameter value
131     * @return this
132     */
133    Connection form(String name, String value);
134
135    /**
136     * {@link RateLimit} object to keep updated.
137     *
138     * @param limit
139     *            {@link RateLimit} object
140     * @return this
141     */
142    Connection rateLimit(RateLimit limit);
143
144    /**
145     * Invokes the call and returns a single {@link FlattrObject} as response.
146     *
147     * @return result {@link FlattrObject}, never {@code null}
148     * @throws FlattrException
149     *             if the call could not be invoked or the web service returned an error
150     * @throws MarshalException
151     *             if more or less than a single FlattrObject were returned
152     */
153    FlattrObject singleResult() throws FlattrException;
154
155    /**
156     * Invokes the call and returns a Collection of {@link FlattrObject} as response.
157     *
158     * @return result collection of {@link FlattrObject}, may be empty but never
159     *         {@code null}
160     * @throws FlattrException
161     *             if the call could not be invoked or the web service returned an error
162     */
163    Collection<FlattrObject> result() throws FlattrException;
164
165}