Дополнительное задание #1

Для выполнения задания надо самостоятельно изучить этот материал.

В этом задании вы начнете разработку программы для игры в Боггл. Хотя правила игры в Боггл очень просты, разработка программы не выглядит так же просто. За несколько недель мы разработаем различные компоненты этой игры, и затем начнем собирать их вместе в единое приложение. Вам необходимо выполнить столько заданий, сколько вы не сдали вовремя в течении семестра. Остальные задания необходимые для завершения проекта делать не обязательно. Можете закончить проект, если хотите.

Списки слов

В игре Боггл придется много работать со списками слов, по этому нужен хороший вспомогательный класс для управления списками слов. На этой неделе, основная задача создать класс "список слов" который хранит словарь разрешенных слов, и может использоваться для записи слов которые отгадывают игроки. (Этот класс можно назвать, например WordList.)

Вот спецификация, в которой перечислены необходимые функции класса:

• Сделайте так, чтобы ваш класс списка слов использовал библиотечный класс java.util.Set, реализующий быстрый поиск и проверку вхождения в множество. It is для большинства операций нет необходимости сортировать списки слов.

• Используйте технологию обобщенного программирования Java (generics).

• Сделайте конструктор, который создает пустой список слов.
• Напишите аксессор size() который возвращает количество слов в списке.

• Напишите метод "добавление слова" для того чтобы добавлять новые слова к списку слов. Ниже приведены дополнительные требования для этого функционала:

  • Удаляйте пробелы перед и после каждого слова, в случае если в строках входного файла имеются пробелы. Если оказывается, что "слово" состоит только из пробелов не добавляйте его в список (просто игнорируйте его).
  • Переводите каждое слово в нижний регистр, чтобы упростить сравнение строк!

  (Подсказка: Эту "предварительную обработку" слова нужно поместить во вспомогательный метод.)

• Сделайте другой конструктор который получает через параметры объект java.io.File, и считывает все слова из указанного файла. Каждое слово расположено на отдельной строке во входном файле. Воспользуйтесь классом java.io.BufferedReader для упрощения чтения данных из файла по строкам. Каждое слово должно быть обработано при добавлении в список. (Подсказка: не повторяйте код если он уже где то написан, выделяйте такой код в отдельные процедуры и используйте их!)

  Этот конструктор должен генерировать исключение java.io.IOException если файл не может быть открыт, или произошла другая ошибка во время загрузки файла.

• Напишите метод, который возвращает true если список слов содержит указанное слово. Например, сигнатура метода может быть такая boolean containsWord(String word). Обработайте аргумент перед тем, как проверять имеется ли он в списке слов. (Можно все упростить выделив код обработки в отдельную вспомогательную функцию.)

• Напишите метод, добавляющий к списку слов другой список слов. Например если есть два списка слов a и b, тогда a.addWordList(b) должен изменять a так, чтобы он содержал слова из обоих списков a и b.

  Так как слова в другом списке уже обработаны, не нужно беспокоиться об обработке слов, как это делалось в методе "добавления слов".

  (Подсказка: этот метод можно сделать очень просто воспользовавшись подходящим методом класса Set, и private методами класса WordList. Так как это метод класса WordList, он может вызывать private методы любого объекта WordList.)

• Сделайте метод void WordList.subtract(WordList), который вычисляет разность между объектами WordList. Например, если есть два списка слов a и b, то a.subtract(b) удаляет из списка a слова содержащиеся в списке b.

Тестирование класса Список-слов

В этом задании вы должны сделать только основные тесты списка слов. Создайте простой тестовый класс для вашего списка слов, который делает следующее:

• Получает один аргумент из командной строки, который задает путь/имя текстового файла для загрузки. Если в командной строке нет аргументов или указано больше одного аргумента выведите сообщение об ошибке и завершите работу.
• Создайте объект список-слов содержимое которого загружается из указанного файла. Если во время загрузки происходит ошибка, напечатайте подходящее сообщение. Иначе, напечатайте общее число слов во входном файле.

Назовите этот класс, к примеру TestWordList.

Проверьте, что ваш список слов и тестовый класс компилируются. Затем, проверьте вашу программу с этим файлом. (Сначала разархивируйте его! В Linux: unzip sowpods.zip) У вас должно получиться всего 267,751 слов.

Документация Java API

Всегда начиная работу над проектом содержащим более чем два-три класса, следует позаботиться о создании документации API вашего проекта. Создание такой документации вручную обычно слишком затратное дело, но к счастью, компания Sun создала для нас очень удобный инструмент, который называется javadoc. Он может создавать все виды документации Java API из исходного кода.

Снабдите ваш класс полной документацией используя правила комментариев и аннотаций Javadoc.В частности:

• Сам класс. Включая тэг @author для класса.
• Каждое поле в классе.
• Каждый метод в классе. Включая:
  • Тэг @param для каждого аргумента метода, в котором также следует указать недопустимые значения аргумента (например "Аргумент file не может быть null.").
  • Спецификация @throws для каждого проверяемого исключения, которое генерирует метод, включая краткое описание обстоятельств при которых генерируется это исключение.
  • Для всех функций кроме простых аксессоров, укажите тэг @return с описанием возвращаемого значения.

После окончания документирования класса, создайте документацию Javadoc API с помощью этой команды:

    javadoc -d docs *.java

(Или, можно просто указать WordList.java вместо *.java; в этом задании это не важно.)

Аргумент -d docs заставляет javadoc поместить созданные файлы в каталог ./docs; javadoc создаст этот каталог для вас, если он еще не существует.

Затем откройте в веб браузере файл index.html в вашем каталоге docs и проверьте, что ваша документация правильная и полная.

Это все что от вас требуется в этом задании. Когда закончите, отправьте ваши файлы исходного кода (но не файлы .class, или файлы созданные javadocs, или список слов!) на проверку.

Если вы хотите улучшить ваш список слов, можете попробовать выполнить это задание и получить "дополнительные баллы".

Вы возможно заметили что сжатый файл слов занимает 687Кб , а после распаковки его размер становится равным 2.9Мб. Обычный текст сжимается довольно хорошо. Добавьте к своему списку возможность считывать данные прямо из ZIP и/или gzip архива.

Сначала нужно добавить конструктор с параметром InputStream. Так можно загрузить файл из java.util.zip.GZIPInputStream или java.util.zip.ZipInputStream не добавляя ничего к коду класса списка слов.

Затем добавьте статические методы к своему классу списку-слов, который загружает список слов из файлов этого типа. Например, вы можете создать такие функции:

    // Загрузка списка слов из gzip архива.
    public static WordList loadFromGZipFile(File gzipFile) throws IOException

    // Загрузка списка слов из zip архива.
    public static WordList loadFromZipFile(File zipFile, String zipEntryName)
        throws IOException

gzip архивы содержат только один файл, поэтому эту функцию сделать легче. Но, zip архивы могут содержать несколько файлов, поэтому надо указывать дополнительно имя файла в zip архиве zipEntryName.

(Как вариант, ваш метод загрузки из zip архива может быть рассчитан на то, что .zip архив содержит только ОДИН файл , и будет выдавать исключение если это не так.)

Задокументируйте детали реализации ваших функций загрузки! Как обычно используйте комментарии javadoc.

Copyright (C) 2015, California Institute of Technology. All rights reserved.