← joda-money  /  src/main/java/org/joda/money/BigMoneyProvider.java

1 
/*
2 
 *  Copyright 2009-present, Stephen Colebourne
3 
 *
4 
 *  Licensed under the Apache License, Version 2.0 (the "License");
5 
 *  you may not use this file except in compliance with the License.
6 
 *  You may obtain a copy of the License at
7 
 *
8 
 *      http://www.apache.org/licenses/LICENSE-2.0
9 
 *
10 
 *  Unless required by applicable law or agreed to in writing, software
11 
 *  distributed under the License is distributed on an "AS IS" BASIS,
12 
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 
 *  See the License for the specific language governing permissions and
14 
 *  limitations under the License.
15 
 */
16 
package org.joda.money;
17 

      

      
      

        18
        
/**

      

      
      

        19
        
 * Provides a uniform interface to obtain a {@code BigMoney}.

      

      
      

        20
        
 * <p>

      

      
      

        21
        
 * This interface provides an abstraction over {@link Money} and {@link BigMoney}.

      

      
      

        22
        
 * In general, applications should use the concrete types, not this interface.

      

      
      

        23
        
 * However, utilities and frameworks may choose to make use of this abstraction.

      

      
      

        24
        
 * <p>

      

      
      

        25
        
 * Implementations of {@code BigMoneyProvider} may be mutable.

      

      
      

        26
        
 * To minimise the risk of the value of the provider changing while processing,

      

      
      

        27
        
 * any method that takes a {@code BigMoneyProvider} as a parameter should convert

      

      
      

        28
        
 * it to a {@code BigMoney} immediately and use that directly from then on.

      

      
      

        29
        
 * The method {@link BigMoney#of(BigMoneyProvider)} performs the conversion

      

      
      

        30
        
 * safely with null checks and is recommended for this purpose.

      

      
      

        31
        
 * <p>

      

      
      

        32
        
 * This interface makes no guarantees about the immutability or

      

      
      

        33
        
 * thread-safety of implementations.

      

      
      

        34
        
 */

      

      
      

        35
        
public interface BigMoneyProvider {

      

      
      

        36
        

      

      
      

        37
        
    /**

      

      
      

        38
        
     * Returns a {@code BigMoney} instance equivalent to the value of this object.

      

      
      

        39
        
     * <p>

      

      
      

        40
        
     * It is recommended that {@link BigMoney#of(BigMoneyProvider)} is used in

      

      
      

        41
        
     * preference to calling this method directly. It is also recommended that the

      

      
      

        42
        
     * converted {@code BigMoney} is cached in a local variable instead of

      

      
      

        43
        
     * performing the conversion multiple times.

      

      
      

        44
        
     *

      

      
      

        45
        
     * @return the converted money instance, never null

      

      
      

        46
        
     * @throws RuntimeException if conversion is not possible

      

      
      

        47
        
     */

      

      
      

        48
        
    public abstract BigMoney toBigMoney();

      

      
      

        49
        

      

      
      

        50
        
}

      

      
      

        51