Документация PDF - ATokS

JSDatаBase
(JAVA SIMPLE DATA BASE V.1.0)
Предисловие (Болтовня)
Эта библиотека представляет сбой базу данных реализованную на яве, для хранения
информации. Очень часто приходится писать программы, которые должны хранить
данные и не только несколько записей, но и до огромных банков, к примеру
телефонная книга города "Нягань".
Я сам частенько сталкивался с проблемой хранения информации например мой
дневник для хранения и вырешивания оценок NotenBank v 1.0 по адрессу
(http://atoks.bplaced.net/index.php?action=soft&top=7&lang=ru) и многое другое.
Конечно многие спросят «А зачем велосипед заново изобретать? Ведь есть куча
достойных и проверенных как MySQL- , XML- database», да я согласен. Но вот
ситуация такая, мне нужна была база данных пользование которой имеет сходство с
MySQL но не требует ни какого дополнительного сервера для работы. По этому я и
написал не большую библиотечку, которая позволяет сохранять данные в одном файле,
который может быть прочитан и переработан моими ява программами. К тому же
обсолютно бесплатно и для мелких проектов довольно не плохая вещь.
Я подключал эту библиотеку уже к трём проектам, пока ни каких багов не обнаружено.
По этому я решил поделиться с обществом моей библиотечкой, а вдруг кому
понадобится.
Плюсы обнаруженные мной ☺
+ САМЫЙ ОГРОМНЫЙ БЕСПЛАТНАЯ
+ Работает локально на машине
+ не требует ни каких дополнительных установок, которые за частую пугают
пользователей
+ простая в пользование
+ маленький размер (на диске)
+ довольно быстрая при 1000000 записях не насколько не отстают от MySQL – банка.
+ так как написанная полностью на яве должна быть кросс платформенной, но я её
тестил только на Windows.
+ есть русская документация
Описание
(Stand-Alone-Database) База данных для хранения информации на локальной машине.
Хотя с помощью Output и Input потоков можно попробывать и удалённо. ;-)
Вся База храниться в одном файле, в виде таблиц. Внутренне JSDatаBase работает со
String и хранит всю информацию именно в этой форме.
JSDatаBase состоит из двух классов JSDataBase и JSDataTable оба класса могут быть
использованны отдельно, т.е. JSDataTable может так же автономно работать как и
JSDataBase.
Содержание класса JSDataBase
1. Vector<String> getTableNames();
2. boolean createTable(String tab_name, String kopf);
3. boolean createTable(String tab_name, String kopf, String autoWert);
4. SJDatenTabelle getTable(String tab_name);
5. boolean renameTable(String alteName, String neueName);
6. boolean removeTable(String tab_name);
7. String[] getHeadOf(String tab_name);
8. boolean addColumnsInTo(String tab_name, String col);
9. boolean removeColumnsFrom(String tab_name, String col);
10. boolean renameColumnsFrom(String tab_name, String col);
11. boolean insertInTo(String tab_name, String ds);
12. Vector<String[]> selectFrom(String tab_name, String beschrenkung,
String bedingung);
13. Vector<String[]> updateOf(String tab_name, String set, String
bedingung);
14. Vector<String[]> deleteFrom(String tab_name, String bedingung);
15. boolean saveTable(String tab_name, OutputStream os);
16. boolean saveTable(String tab_name, File file);
17. boolean loadTable(InputStream is, boolean replace);
18. boolean loadTable(File file, boolean replace);
19. boolean save(OutputStream os) ;
20. boolean save(File file);
21. boolean load(InputStream is);
22. boolean load(File file);
23. String sqlDump();
1) getTableNames();
Эта функция возвращает Vector<String> со всеми именами таблиц которые уже
занесены в базу данных. Если getTableNames().size() == 0 то в базе нет таблиц, база
пуста.
2) createTable(String tab_name, String kopf);
Эта функция создает таблицу с именем которое было передано в параметр tab_name и
с заголовком который был передан в параметре kopf если функция возвращает true то
таблица успешно создана в случае возвращения false таблица была не создана,
возможные причины: не верные параметры или таблица с таким именем уже
существует.
Пример:
JSDataBase db = new JSDataBase();
db.createTable("Test", "ID, Name");
в этом случае будит создона следующая таблица.
Test
ID
Name
3) createTable(String tab_name, String kopf, String autoWert);
Эта функция создаёт таблицу по той же структуре что и createTable(String
tab_name, String kopf); только с одним дополнением autoWert это число которое
может использоваться как Primary Key, так как в этот столбец будет сохранён индекс
каждой записи. Этот индекс ни когда не повторяется. autoWert указывает, какой
столбец должен работать как счётчик.
Пример:
JSDataBase db = new JSDataBase();
db.createTable("User", "ID, Name, Adresse", "ID");
В этом случае будит создана следующая таблица у которой столбец ID перенимает
работу счётчика. Изменять содержание этого столбца не возможно.
ID
User
Name
Adresse
4) getTable(String tab_name);
Эта функция возвращает таблицу с именем переданным в параметре tab_name или
null если таблица с таким именем не существует.
5) renameTable(String alteName, String neueName);
Функция переименовывает таблицу. alteName Имя таблицы которая должна быть
переименована. neueName новое имя.
Возвращает true если успешно переименованная или false если таблица не может быть
переименованная. Причины: Таблица с именем alteName не существует или таблица
с именем neueName уже существует.
6) removeTable(String tab_name);
Функция удаляет таблицу с именем tab_name.
Возвращает true если таблица удачно удалена или false если таблица не может быть
удалена. Причина: таблица с именем tab_name не найдена.
7) getHeadOf(String tab_name);
Функция возвращает массив String[] с заголовком таблицы с именем tab_name.
Или null если таблица с таким именем не существует.
8) addColumnsInTo(String tab_name, String col);
Функция добавляет новые столбцы с именами и содержимым переданным в параметре
col в таблицу с именем переданным в параметре tab_name.
Возвращает true если столбцы были удачно занесены или false если столбцы небыли
занесены. Причина: таблица с именем tab_name не найдена или синтаксис col не
верен или один из желаемых столбцов уже существует в таблице.
Пример:
JSDataBase db = new JSDataBase();
db.createTable("User", "ID, Name, Adresse", "ID");
// Добавляем Столбцы Пол с Содержимым Муж
// и столбец Возрост пустой по умолчанию
db.addColumnsInTo("User", "Sex='Муж', Age=''");
С начало будет создана следующая таблица
User
Name
ID
Adresse
Затем, эта таблица будит на два столбца увеличенная.
ID
Name
User
Adresse
Sex
Age
Если бы таблица перед добавлением столбцов содержала бы уже данные, то после
добавления столбцов Sex и Age в этом случае данные были бы подложенные в столбце
Sex на Муж. т.е. выглядело бы так:
Таблица до добавления.
User
Name
Петров
Иванов
ID
1
2
Adresse
Город грёз
с. Мендюкено
Таблица после добавления.
ID
1
2
Name
Петров
Иванов
User
Adresse
Город грёз
с. Мендюкено
Sex
Муж
Муж
Age
ВНИМАНИЕ
Следующий код является синтаксически не верным.
db.addColumnsInTo("User", "Sex, Age");
Новые столбцы должны быть написанные с содержимым по умолчанию. Как в
примере.
db.addColumnsInTo("User", "Sex='Муж', Age=''" );
9) removeColumnsFrom(String tab_name, String col);
Функция удаляет столбцы с именами переданным в параметре col из таблицы с
именем переданным в параметре tab_name.
Возвращает true если столбцы были удачно удалены или false если столбцы небыли
удалены . Причина: таблица с именем tab_name не найдена или синтаксис col не
верен или один из желаемых столбцов не существует в таблице или же Вы пытаетесь
удалить все столбцы (Таблица без столбцов - не таблица).
Пример:
JSDataBase db = new JSDataBase();
db.createTable("User", "ID, Name, Adresse", "ID");
db.addColumnsInTo("User", "Sex='Man', Age=''");
// Удаляем столбцы ID и Sex
db.removeColumnsFrom("User", "ID, Sex");
Таблица до удаления:
ID
1
2
Name
Петров
Иванов
User
Adresse
Город грёз
с. Мендюкено
Таблица после удаления:
Name
Петров
Иванов
User
Adresse
Город грёз
с. Мендюкено
Age
Sex
Муж
Муж
Age
10) renameColumnsFrom(String tab_name, String col);
Функция переименовывает столбцы переданные в параметре col в таблице с именем
переданным в параметре tab_name.
Возвращает true если столбцы были удачно переименованные или false если столбцы
небыли переименованные. Причина: таблица с именем tab_name не найдена или
синтаксис col не верен или один из желаемых столбцов не существует в таблице или
неовое имя уже существует или пустое.
Пример:
JSDataBase db = new JSDataBase();
db.createTable("User", "ID, Name, Adresse", "ID");
db.addColumnsInTo("User", "Sex='Man', Age=''");
db.removeColumnsFrom("User", "ID, Sex");
// Переименовываем столбцы Adresse и Age в Home и Born
db.renameColumnsFrom("User", "Adresse='Home', Age='Born'");
Таблица до переименоания
Name
User
Adresse
Age
Таблица после переименовывания
User
Name
Home
Born
11) insertInTo(String tab_name, String ds);
Функция добавляет новую строку ds в табилцу с именем tab_name.
Возвращает true если строка была удачно добавленная или false если строка не была
добавленная.
Правила добавки строки.
Допустим у нас существует таблица со следующей структурой.
User
Name
Home
Born
Для того чтобы добавить новую стоку нужно в параметр ds прописать следующее:
(Имя_Столбца = 'Содержание') если нужно внести записи в несколько столбцов, то
нужно и х разделить запятой, например так (Имя_Столбца1 = 'Содержание1',
Имя_Столбца2 = 'Содержание2', и.д. ) соблюдать очерёдность столбцов не обязательно,
содержание будет добавленное по имени столбца. Содержимое всегда должно быть
окружено символом '. Знак ровно перед именем столбца говорит что следующее после
него содержание должно быть записанное в этот столбец.
Пример:
Добавляем содержимое в выше указанную таблицу.
JSDataBase db = new JSDataBase();
db.createTable("User", "ID, Name, Adresse", "ID");
db.addColumnsInTo("User", "Sex='Man', Age=''");
db.removeColumnsFrom("User", "ID, Sex");
db.renameColumnsFrom("User", "Adresse='Home', Age='Born'");
// Добовляем содержимое
db.insertInTo("User", "Name='Smith', Born='12.09.1981', Home='USA'");
после этого таблица выглядит следующим образом:
Name
Smith
User
Home
USA
Born
12.09.1981
Теперь добавим содержимое с пустыми столбцами.
// Добовляем содержимое с пустыми столбцами
db.insertInTo("User", " Home='Нягань', Name='Сидоров'");
Результат:
Name
Smith
Сидоров
User
Home
USA
Нягань
Born
12.09.1981
ВНИМАНИЕ
Для использования зарезервированного символа
'
в содержании пожалуйста
экранируйте его при помощи \\. Например следующий текст
I’m Smith
для записи в Базу должен выглядеть следующим образом.
I\\’m Smith
12) selectFrom(String tab_name, String beschrenkung, String bedingung);
Функция извлекает содержимое из таблицы с именем tab_name на определённых
условиях прописанных в параметре bedingung.
Возвращает Vector<String[]> с содержимым, ограниченное параметром
beschrenkung, которое соотвествует условиям заданным в параметре bedingung.
Так как эта база называется SIMPLE, одним из её ограничений является логический
оператор AND который представлен здесь как запятая. Все остальные операторы
отсутствуют, так как в большинстве случаев хватает одного AND.
Использование операторов * разрешено, здесь как и везде этот оператор стоит за ВСЁ.
Т.е. если вам нужно выдернуть всё из таблиц то пишите следующее:
Vector<String[]> content = db.selectFrom("User", "*", "*");
Содержимое сохранённое в переменную content будет иметь структуру заголовка
таблицы описанном в пункте 7) getHeadOf(String tab_name);.
К примеру следующая таблица
Name
Smith
Сидоров
User
Home
USA
Нягань
Born
12.09.1981
Вызов функции getHeadOf("User") вернёт следующий массив:
String[]{ "Name" , "Home" , "Born" };
Исходя из этого, все массивы в переменной content будут иметь содержание в той же
структуре. К примеру:
String[]{ "Smith" , "USA" , "12.09.1981" };
String[]{ "Сидоров" , "Нягань" , "" };
И если нужно извлечь только имена, то просто извлекаем содержимое из массивов с
индексам который совпадает с индексам "Name" в заголовке таблицы.
Чтобы избежать лишней обработки информации, можно при получении содержимого
из таблицы, при помощи функции selectFrom, в параметре beschrenkung указать
те условия которые определят порядок построения содержимого в массивах, также
можно указать какие столбцы должны быть найдены, а какие нет. Возможно даже
множественное возвращение одного столбца.
Пример к той же таблице:
Vector<String[]> content = db.selectFrom("User", "Home, Name, Home", "*");
Здесь специально, в ограничении, столбцы записанные в другом порядке как заголовок
таблицы и столбец Home прописан два раза.
После вызова этой функции, все массивы в переменной content будут иметь
содержание со структурой "Home, Name, Home".
String[]{ "USA" , "Smith" , "USA" };
String[]{ "Нягань" , "Сидоров" , "Нягань" };
Теперь можно пройтись по всем массивам и выбрать нужную информацию.
Но и это можно с экономить, если при вызове функции selectFrom, в параметре
bedingung указать условие которое ограничит поиск содержимого.
Пример к той же таблице:
Vector<String[]> content = db.selectFrom("User", "Born, Name, Home", "Born=''");
После вызова этой функции, все массивы в переменной content будут иметь
содержание со структурой "Born, Name, Home".
String[]{ "" , "Сидоров" , "Нягань" };
13) updateOf(String tab_name, String set, String bedingung);
Функция обновляет содержимое в таблице с именем tab_name на определённых
условиях прописанных в параметре bedingung. Оператор * разрешен.
Возвращает Vector<String[]> со старым содержимым. В случае если размер вектора
равен нулю, значит обновление не произошло.
Синтаксис параметра bedingung такой же как у функции 12) selectFrom(...);
Синтаксис параметра set такой же как у ds в функции insertInTo(...);
Пример:
Таблица до обновления
Name
Smith
Сидоров
User
Home
USA
Нягань
Born
12.09.1981
db.updateOf("User", "Born='29.02.1978'", "Born=''");
После вызова этой функции записи в которых столбец Born пустой, получат значение
'29.02.1978'.
Таблица после обновления
Name
Smith
Сидоров
User
Home
USA
Нягань
Born
12.09.1981
29.02.1978
14) deleteFrom(String tab_name, String bedingung);
Функция удаляет записи из таблице с именем tab_name на определённых условиях
прописанных в параметре bedingung. Оператор * разрешен.
Возвращает Vector<String[]> с удалёнными записями. В случае если размер вектора
равен нулю, значит удаление не произошло.
Синтаксис параметра bedingung такой же как у функции 12) selectFrom(...);
Пример:
Name
Smith
Сидоров
User
Home
USA
Нягань
Born
12.09.1981
29.02.1978
db.deleteFrom("User", "Name='Smith'");
Таблица после удаления
Name
Сидоров
User
Home
Нягань
Born
29.02.1978
14)-22) save / load функции
С помощью этих функций возможно сохранение и загрузка базы в файл.
Те функции которые предназначенные для сохранения и загрузки отдельных таблиц
требуют указание имени таблицы или же указание можно ли переписывать таблицу в
базе если таблица с таким именем уже существует.
tab_name = Имя таблицы которая должна быть сохранена
replace = Флаг который помечает должна ли существующая таблица быть
переписанной.
22) sqlDump();
Функция возвращает String который содержит SQL-Dump полностью всей базы
данных. Этот результат можно скопировать и вставить к примеру в phpmyadmin для
генерации/копирования базы.
Пример к верхней таблице.
-----
JSDataBase SQL Dump
Author: Aleksej Tokarev
Dump date: Sun Feb 20 09:13:27 CET 2011
JSDataBase vesion 1.0
--- Table struct for `User`
-CREATE TABLE IF NOT EXISTS `User` (
`Name` TEXT DEFAULT NULL,
`Home` TEXT DEFAULT NULL,
`Born` TEXT DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=latin1 ;
INSERT INTO `User` (`Name`,`Home`,`Born`) VALUES
('Сидоров','Нягань','29.02.1978');
-- ------------------------------------
Дополнительно
Для того чтобы получить дополнительную информацию от таблиц используйте
функцию 4) getTable(String tab_name);
Количество записей в таблице
getTable(String tab_name).getRecordsCount(); // Integer
Имя столбца которы работает как счётчик
getTable(String tab_name).get_auto_increment(); // String
Актуальный счётчик
getTable(String tab_name).get_increment();
Ну вот вобщем-то и всё что я хотел описать в этой документации.
Пользуйтесь на здоровее. Если есть вопросы, комментарии, предложения пожалуйста
обращайтесь ко мне через форму контакта на моей странице
http://atoks.bplaced.net/index.php?action=contact