Formatter.java
01 /*
02  * SPDX-License-Identifier: Apache-2.0
03  *
04  * Copyright 2008-2017 the original author or authors.
05  *
06  * Licensed under the Apache License, Version 2.0 (the "License");
07  * you may not use this file except in compliance with the License.
08  * You may obtain a copy of the License at
09  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package griffon.core.formatters;
19 
20 import javax.annotation.Nullable;
21 
22 /**
23  <p>Strategy for parsing and formatting instances from and to their literal representation</p>
24  *
25  @param <T> the type of instances this {@code Formatter} can handle.
26  @author Andres Almiray
27  @since 2.0.0
28  */
29 public interface Formatter<T> {
30     /**
31      <p>Formats an instance into its literal representation.</p>
32      <p>The resulting {@code String} may be set as an argument to {@link Formatter#parse}
33      * resulting in a similar instance as the input.</p>
34      *
35      @param obj the instance to be formatted
36      @return A {@code String} representing the instance's state.
37      */
38     @Nullable
39     String format(@Nullable T obj);
40 
41     /**
42      <p>Parses a literal representation into an instance of type {@code T}.</p>
43      <p>The resulting instance {@code T} may be set as an argument to {@link Formatter#format}
44      * resulting in an equal {@code String} as the input.</p>
45      *
46      @param str the {@code String} to be parsed
47      @return an instance of type {@code T} whose state is initialized given the
48      * parameters of the input {@code String}.
49      @throws ParseException if the {@code String} cannot be parsed.
50      */
51     @Nullable
52     T parse(@Nullable String strthrows ParseException;
53 }