Дизайн API библиотеки

На написание данной статьи меня натолкнула библиотека EasyCamera, которая упрощает сложный вызов Android Camera API (статья о ней).
Часто приходится сталкиваться с тем, что для работы той или иной библиотеки необходимо прочитать документацию или поискать подробные примеры её использования. Например, чтобы заставить ту же Android Camera API показать экран видоискателя, нужно вызвать сначала метод setPreviewDisplay(holder), а затем уже startPreview(). Это не всегда очевидно и не очень удобно.
Поэтому при проектировании библиотеки следует учитывать некоторые параметры, а именно:
1. Классы и методы должны быть понятны пользователю (в данном случае пользователем является программист).
2. Не должно быть "подводных камней", когда вызов двух методов в различной последовательности приводит к ошибке.
3. Библиотека должна быть максимально простой, чтобы программисту не доводилось каждый раз читать документацию или лезть в код.

В качестве примера возьмём пример работы алгоритма Маркова.

Открыть спойлер

Закрыть спойлер

[копировать] [скачать]

1. import java.util.ArrayList;
2.  
3. public class AlgorithmMarkov {
4.  
5.     public static void main(String[] args) {
6.         /* Исходные данные */
7.         // Слово
8.         String P = "213022";
9.         // Правила подстановки
10.         ArrayList<Replacement> rules = new ArrayList<>();
11.         rules.add(new Replacement("~0", "00~"));
12.         rules.add(new Replacement("~1", "01~"));
13.         rules.add(new Replacement("~2", "10~"));
14.         rules.add(new Replacement("~3", "11~"));
15.         rules.add(new Replacement("~", "", true)); // заключительная подстановка
16.         rules.add(new Replacement("", "~"));
17.  
18.         /* Реализация */
19.         int step = 0;
20.         boolean iterate = true;
21.         while(iterate && (step < 1000)) {
22.             final String pref = P;
23.             for (Replacement current : rules) {
24.                 String replaceString = replaceFirst(P, current);
25.                 if (!replaceString.equals(P)) {
26.                     P = replaceString;
27.                     step++;
28.                     // Если произошла заключительная подстановка - выходим
29.                     if (current.endless) iterate = false;
30.                     break;
31.                 }
32.             }
33.             if (pref.equals(P)) break;
34.             System.out.println(step+" P=\""+P+"\"");
35.         }
36.     }
37.  
38.     private static String replaceFirst(String str, Replacement replace) {
39.         if (replace.from.length() == 0) return replace.to + str;// _ -> *
40.         return str.replaceFirst(replace.from, replace.to);
41.     }
42.  
43.  
44.     private static class Replacement {
45.  
46.         private final String from, to;
47.         /** Заключительная подстановка */
48.         private final boolean endless;
49.  
50.         private Replacement(String from, String to) {
51.             this(from, to, false);
52.         }
53.  
54.         private Replacement(String from, String to, boolean endless) {
55.             this.from = from;
56.             this.to = to;
57.             this.endless = endless;
58.         }
59.  
60.     }
61. }

Сразу оговорюсь, это вообще-то не библиотека, это просто пример. Но мы сейчас сделаем из него удобную библиотеку.
Поехали!

Первым делом, следует обратить внимание на то, что исходные параметры (правила подстановки) добавляются в список таким образом:
Это не очень удобно.
Поэтому давайте сделаем свой класс Rules, в котором добавлять правила будет проще.
Код вроде бы небольшой, но на парочку моментов следует обратить внимание.
Во-первых, я запретил вызов конструктора класса, сделав его приватным. Это значит, что вызвать new Rules() я уже не смогу из другого класса.
Второе, что я сделал, это добавил "фабрику" - статический метод create(), который создаёт объект класса Rules.
Эти два шага позволяют создать объект вот такой строчкой кода:
Rules rules = Rules.create();
Конечно, в данном случае можно было этого не делать и пользоваться конструктором класса, но в больших классах/библиотеках фабрика позволяет красиво и понятно создать объект. Вот небольшой пример использования фабрики:
В Java SE есть несколько видов границ элементов (кнопок, текстовых полей и т.д) - пустая граница, граница в виде линии, "выдавленная" граница и т.д. Мы можем явно создать объект через конструктор класса:
а можем воспользоваться фабрикой:
Если после вызова конструктора нужно ещё как-нибудь подготовить объект, то фабрика поможет в этом.

Идём дальше, в каждый метод я добавил return this; зачем?
А затем, чтобы получился вот такой красивый вызов:
А теперь сравните это с тем, что было в первоначальном варианте. Думаю, очевидно, какой код красивее и понятнее.

Точно также сделаем класс Markov.

Открыть спойлер

Закрыть спойлер

[копировать] [скачать]

1. public final class Markov {
2.  
3.     public static Markov create() {
4.         return new Markov();
5.     }
6.  
7.     public static Markov with(Rules rules) {
8.         final Markov markov = new Markov();
9.         markov.rules(rules);
10.         return markov;
11.     }
12.  
13.     private PrintStream printStream;
14.     private Rules rules;
15.     private int iterateLimit;
16.  
17.     private Markov() {
18.         iterateLimit = 1000;
19.         printStream = System.out;
20.     }
21.  
22.     public Markov rules(Rules rules) {
23.         this.rules = rules;
24.         return this;
25.     }
26.  
27.     public Markov iterateLimit(int iterateLimit) {
28.         this.iterateLimit = iterateLimit;
29.         return this;
30.     }
31.  
32.     public Markov printStream(PrintStream printStream) {
33.         this.printStream = printStream;
34.         return this;
35.     }
36.  
37.     public Markov process(String word) {
38.         if (rules == null) throw new IllegalArgumentException("Rules is empty");
39.  
40.         int step = 0;
41.         boolean iterate = true;
42.         while(iterate && (step < iterateLimit)) {
43.             final String prev = word;
44.             for (Object rule : rules) {
45.                 Replacement current = (Replacement) rule;
46.                 String replaceString = replaceFirst(word, current);
47.                 if (!replaceString.equals(word)) {
48.                     word = replaceString;
49.                     step++;
50.                     // Если произошла заключительная подстановка - выходим
51.                     if (current.endless) iterate = false;
52.                     break;
53.                 }
54.             }
55.             if (prev.equals(word)) break;
56.             printStream.println(step + " P=\"" + word + "\"");
57.         }
58.         return this;
59.     }
60.  
61.     private static String replaceFirst(String str, Replacement replace) {
62.         if (replace.from.length() == 0) return replace.to + str;// _ -> *
63.         return str.replaceFirst(replace.from, replace.to);
64.     }
65. }

В этот раз у нас два фабричных метода: create() - просто инициализирует класс и with(Rules rules) - инициализирует класс с набором правил.
Конструктор всё также приватный, чтобы пользователь не мог вмешаться в отлаженную работу библиотеки.

Вот теперь работа с нашей библиотекой будет выглядеть так:

Открыть спойлер

Закрыть спойлер

[копировать] [скачать]

1. public static void main(String[] args) {
2.     Rules rules4to2 = Rules.create()
3.             .add("~0", "00~")
4.             .add("~1", "01~")
5.             .add("~2", "10~")
6.             .add("~3", "11~")
7.             .add("~", "", true) // заключительная подстановка
8.             .add("", "~");
9.  
10.     Rules rules16to2 = Rules.create()
11.             .add("~0", "0000~")
12.             .add("~1", "0001~")
13.             .add("~2", "0010~")
14.             .add("~3", "0011~")
15.             .add("~4", "0100~")
16.             .add("~5", "0101~")
17.             .add("~6", "0110~")
18.             .add("~7", "0111~")
19.             .add("~8", "1000~")
20.             .add("~9", "1001~")
21.             .add("~A", "1010~")
22.             .add("~B", "1011~")
23.             .add("~C", "1100~")
24.             .add("~D", "1101~")
25.             .add("~E", "1110~")
26.             .add("~F", "1111~")
27.             .add("~", "", true) // заключительная подстановка
28.             .add("", "~");
29.     Markov.create()
30.             .rules(rules4to2)
31.             .process("213022")
32.             .process("1323121321")
33.             .rules(rules16to2)
34.             .process("7F")
35.             .process("CAFEBABE");
36. }

Сначала мы создаём правила для преобразования из четверичного числа в двоичное, потом из HEX в BIN, а затем одним махом получаем результат для нужных нам чисел.

Проект с исходниками (Java SE)