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}