1 /**
2 * Copyright (c) 2012-2015, jcabi.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met: 1) Redistributions of source code must retain the above
8 * copyright notice, this list of conditions and the following
9 * disclaimer. 2) Redistributions in binary form must reproduce the above
10 * copyright notice, this list of conditions and the following
11 * disclaimer in the documentation and/or other materials provided
12 * with the distribution. 3) Neither the name of the jcabi.com nor
13 * the names of its contributors may be used to endorse or promote
14 * products derived from this software without specific prior written
15 * permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package com.jcabi.odesk;
31
32 import com.jcabi.aspects.Immutable;
33 import java.io.IOException;
34 import java.math.BigDecimal;
35 import javax.validation.constraints.NotNull;
36
37 /**
38 * Adjustments.
39 *
40 * @author Yegor Bugayenko (yegor@tpc2.com)
41 * @version $Id: c51cb7d83fb170455c53cef58a4499d7efda97a4 $
42 * @since 0.1
43 */
44 @Immutable
45 public interface Adjustments {
46
47 /**
48 * Make a custom/bonus payment.
49 * @param engagement Engagement reference number
50 * @param charge Amount to be charged from the payer (can be zero)
51 * @param comments Payment comments
52 * @param notes Notes to add to the payment
53 * @return Reference ID of a new adjustment
54 * @throws IOException If fails due to IO problem
55 * @see <a href="http://developers.odesk.com/w/page/25400171/Custom%20Payment%20API">Custom Payment API</a>
56 * @checkstyle ParameterNumber (10 lines)
57 * @since 0.7
58 */
59 @NotNull(message = "adjustment ID is never NULL")
60 String add(
61 @NotNull(message = "engagement ref can't be NULL") String engagement,
62 @NotNull(message = "charge amount can't be NULL") BigDecimal charge,
63 @NotNull(message = "comments can't be NULL") String comments,
64 @NotNull(message = "notes can't be NULL") String notes)
65 throws IOException;
66
67 /**
68 * Get list of all adjustments (their reference IDs).
69 * @return List of them all
70 * @throws IOException If fails due to IO problem
71 * @see <a href="http://developers.odesk.com/w/page/25400171/Custom%20Payment%20API">Custom Payment API</a>
72 */
73 @NotNull(message = "iterable of adjustments is never NULL")
74 Iterable<String> iterate() throws IOException;
75
76 }