diff --git a/docs/DEMAND.md b/docs/DEMAND.md index 2f6275b..196a194 100644 --- a/docs/DEMAND.md +++ b/docs/DEMAND.md @@ -62,7 +62,7 @@ NOTICE: # ./buildconf --force # ./configure --help | grep pthreads -You have to see --enable-pthreads listed. If do not, clear the buidls with this commands: +You have to see --enable-pthreads listed. If do not, clear the builds with this commands: # rm -rf aclocal.m4 # rm -rf autom4te.cache/ diff --git a/docs/STRUCT.md b/docs/STRUCT.md index d909c59..721cac3 100644 --- a/docs/STRUCT.md +++ b/docs/STRUCT.md @@ -18,7 +18,11 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - Join.cpp (join the node candidates to get results) - - Join.h (class, members,, and functions definitions) + - Join.h (class, members and functions definitions) + + - Strategy.cpp + + - Strategy.h - KVstore/ (a key-value store to swap between memory and disk) @@ -26,39 +30,133 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - KVstore.h - - heap/ (a heap of nodes whose content are in memory) - - - Heap.cpp + - ISArray/ - - Heap.h + - ISArray.cpp + + - ISArray.h + + - ISBlockManager.cpp + + - ISBlockManager.h + + - ISEntry.cpp + + - ISEntry.h + + - ISTree/ + + - ISTree.cpp + + - ISTree.h + + - heap/ (a heap of nodes whose content are in memory) + + - ISHeap.cpp + + - ISHeap.h - - node/ (all kinds of nodes in B+-tree) + - node/ (all kinds of nodes in B+-tree) - - Node.cpp (the base class of IntlNode and LeafNode) + - ISIntlNode.cpp - - Node.h + - ISIntlNode.h - - IntlNode.cpp (internal nodes in B+-tree) + - ISLeafNode.cpp - - IntlNode.h + - ISLeafNode.h - - LeafNode.cpp (leaf nodes in B+-tree) + - ISNode.cpp - - LeafNode.h + - ISNode.h - - storage/ (swap contents between memory and disk) + - storage/ - - file.h + - ISStorage.cpp + + - ISStorage.h + + - IVArray/ + + - IVArray.cpp + + - IVArray.h + + - IVBlockManager.cpp + + - IVBlockManager.h + + - IVCacheManager.cpp + + - IVCacheManger.h + + - IVEntry.cpp + + - IVEntry.h + + - IVTree/ + + - IVTree.cpp + + - IVTree.h + + - heap/ (a heap of nodes whose content are in memory) - - Storage.cpp + - IVHeap.cpp - - Storage.h + - IVHeap.h + + - node/ (all kinds of nodes in B+-tree) - - tree/ (implement all tree operations and interfaces) + - IVIntlNode.cpp - - Tree.cpp + - IVIntlNode.h - - Tree.h + - IVLeafNode.cpp + + - IVLeafNode.h + + - IVNode.cpp + + - IVNode.h + + - storage/ + + - IVStorage.cpp + + - IVStorage.h + + - SITree/ + + - SITree.cpp + + - SITree.h + + - heap/ (a heap of nodes whose content are in memory) + + - SIHeap.cpp + + - SIHeap.h + + - node/ (all kinds of nodes in B+-tree) + + - SIIntlNode.cpp + + - SIIntlNode.h + + - SILeafNode.cpp + + - SILeafNode.h + + - SINode.cpp + + - SINode.h + + - storage/ + + - SIStorage.cpp + + - SIStorage.h - Query/ (needed to answer SPARQL query) @@ -70,6 +168,10 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - IDList.h + - ResultFilter.cpp + + - ResultFilter.h + - ResultSet.cpp (keep the result set corresponding to a query) - ResultSet.h @@ -82,6 +184,10 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - Varset.h + - QueryCache.cpp + + - QueryCache.h + - QueryTree.cpp - QueryTree.h @@ -90,6 +196,10 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - GeneralEvaluation.h + - TempResult.cpp + + - TempResult.h + - RegexExpression.h - Signature/ (assign signatures for nodes and edges, but not for literals) @@ -178,6 +288,12 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - BloomFilter.h + - ClassForVlistCache.h + + - VList.cpp + + - VList.h + - - - #### The interface part is listed below: @@ -200,21 +316,19 @@ The flow of answering a SPARQL query is given in [SPARQL Processing](png/查询 - Socket.h -- Main/ (a series of applications/main-program to operate on gStore) + - client_http.hpp - - gload.cpp (import a RDF dataset) + - server_http.hpp - - gquery.cpp (query a database) - - - gserver.cpp (start up the gStore server) - - - gclient.cpp (connect to a gStore server and interact) +- web/ + + - - - - #### More details -To acquire a deep understanding of gStore codes, please go to [Code Detail](pdf/代码目录及概览.pdf). See [use case](pdf/Gstore2.0_useCaseDoc.pdf) to understand the design of use cases, and see [OOA](pdf/OOA_class.pdf) and [OOD](pdf/OOD_class.pdf) for OOA design and OOD design, respectively. +To acquire a deep understanding of gStore codes, please go to [Code Detail](pdf/code_overview.pdf). See [use case](pdf/Gstore2.0_useCaseDoc.pdf) to understand the design of use cases, and see [OOA](pdf/OOA_class.pdf) and [OOD](pdf/OOD_class.pdf) for OOA design and OOD design, respectively. If you want to know the sequence of a running gStore, please view the list below: diff --git a/docs/help/gStore_help.pdf b/docs/help/gStore_help.pdf index 8673245..9dd6047 100644 Binary files a/docs/help/gStore_help.pdf and b/docs/help/gStore_help.pdf differ diff --git a/docs/help/gStore_help.tex b/docs/help/gStore_help.tex deleted file mode 100644 index 32d1539..0000000 --- a/docs/help/gStore_help.tex +++ /dev/null @@ -1,2600 +0,0 @@ -\documentclass[titlepage, a4paper, 12pt]{article} - -%\usepackage{ctex} -\usepackage{lmodern} -\usepackage{ifxetex,ifluatex} -\usepackage{fixltx2e} -\usepackage{amsmath} -\usepackage{txfonts} -\usepackage{amssymb} -\usepackage{times} -\usepackage{graphicx} -\usepackage{epsfig,tabularx,amssymb,amsmath,subfigure,multirow} -%\usepackage{algorithmic} -\usepackage[linesnumbered,ruled,noend]{algorithm2e} -\usepackage[noend]{algorithmic} -\usepackage{multirow} -\usepackage{graphicx,floatrow} -\usepackage{listings} -\usepackage{threeparttable} -%\usepackage{tikz} -\usepackage[T1]{fontenc} -\usepackage{pgfplots} -\usepackage{filecontents} -\usepackage{comment} - -\lstset{% - alsolanguage=Java, - %language={[ISO]C++}, %language为，还有{[Visual]C++} - %alsolanguage=[ANSI]C, %可以添加很多个alsolanguage,如alsolanguage=matlab,alsolanguage=VHDL等 - %alsolanguage= tcl, - alsolanguage= XML, - tabsize=4, % - frame=shadowbox, %把代码用带有阴影的框圈起来 - commentstyle=\color{red!50!green!50!blue!50},%浅灰色的注释 - rulesepcolor=\color{red!20!green!20!blue!20},%代码块边框为淡青色 - keywordstyle=\color{blue!90}\bfseries, %代码关键字的颜色为蓝色，粗体 - showstringspaces=false,%不显示代码字符串中间的空格标记 - stringstyle=\ttfamily, % 代码字符串的特殊格式 - keepspaces=true, % - breakindent=22pt, % - numbers=left,%左侧显示行号 往左靠,还可以为right，或none，即不加行号 - stepnumber=1,%若设置为2，则显示行号为1,3,5，即stepnumber为公差,默认stepnumber=1 - %numberstyle=\tiny, %行号字体用小号 - numberstyle={\color[RGB]{0,192,192}\tiny} ,%设置行号的大小，大小有tiny,scriptsize,footnotesize,small,normalsize,large等 - numbersep=8pt, %设置行号与代码的距离，默认是5pt - basicstyle=\footnotesize, % 这句设置代码的大小 - showspaces=false, % - flexiblecolumns=true, % - breaklines=true, %对过长的代码自动换行 - breakautoindent=true,% - breakindent=4em, % - % escapebegin=\begin{CJK*}{GBK}{hei},escapeend=\end{CJK*}, - aboveskip=1em, %代码块边框 - tabsize=2, - showstringspaces=false, %不显示字符串中的空格 - backgroundcolor=\color[RGB]{245,245,244}, %代码背景色 - %backgroundcolor=\color[rgb]{0.91,0.91,0.91} %添加背景色 - escapeinside=``, %在``里显示中文 - %% added by http://bbs.ctex.org/viewthread.php?tid=53451 - fontadjust, - captionpos=t, - framextopmargin=2pt,framexbottommargin=2pt,abovecaptionskip=-3pt,belowcaptionskip=3pt, - xleftmargin=4em,xrightmargin=4em, % 设定listing左右的空白 - texcl=true, - % 设定中文冲突，断行，列模式，数学环境输入，listing数字的样式 - extendedchars=false,columns=flexible,mathescape=true - % numbersep=-1em -} - -\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex - \usepackage[T1]{fontenc} - \usepackage[utf8]{inputenc} -\else % if luatex or xelatex - \ifxetex - \usepackage{mathspec} - \usepackage{xltxtra,xunicode} - \else - \usepackage{fontspec} - \fi - \defaultfontfeatures{Mapping=tex-text,Scale=MatchLowercase} - \newcommand{\euro}{�} -\fi - -% use upquote if available, for straight quotes in verbatim environments -\IfFileExists{upquote.sty}{\usepackage{upquote}}{} -% use microtype if available -\IfFileExists{microtype.sty}{% -\usepackage{microtype} -\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts -}{} -\usepackage{longtable,booktabs} -\ifxetex - \usepackage[setpagesize=false, % page size defined by xetex - unicode=false, % unicode breaks when used with xetex - xetex]{hyperref} -\else - \usepackage[unicode=true]{hyperref} -\fi -\hypersetup{breaklinks=true, - bookmarks=true, - pdfauthor={}, - pdftitle={Gstore System}, - colorlinks=true, - citecolor=blue, - urlcolor=blue, - linkcolor=magenta, - pdfborder={0 0 0}} -\urlstyle{same} % don't use monospace font for urls -%\setlength{\parskip}{6pt plus 2pt minus 1pt} -\setlength{\emergencystretch}{3em} % prevent overfull lines -\setcounter{secnumdepth}{0} -\setlength{\parindent}{0pt} -%\setlength{\parindent}{2em} -\addtolength{\parskip}{3pt} -\linespread{1.3} - -\begin{document} -\title{\includegraphics[scale=0.3, bb=0 0 385 567]{logo.png} \\ - The handbook of gStore System测试} -%\author{Bookug Lobert\footnote{EECS of Peking University, zengli-bookug@pku.edu.cn}\\[2ex]} -\author{Edited by gStore team \footnote{The mailing list is given in Chapter 13.}} -\date{\today} -%\begin{figure}[b] -% \centering -%　 \includegraphics[scale=0.3,bb=0 0 385 567]{../logo.png} - %\caption{Some description about the picture} -% \label{logo} -%\end{figure} -\maketitle - -\hyperdef{}{MathJaxux5fSVGux5fHidden}{} - -\hyperdef{}{wmd-preview}{} - -\setcounter{tocdepth}{4} -\tableofcontents -\clearpage - -\section{Preface} -The RDF (\emph{R}esource \emph{D}escription \emph{F}ramework) is a family of specifications proposed by W3C for modeling Web objects as part of developing the semantic web. In RDF model, each Web object is modeled as a uniquely named \emph{resource} and denoted by a URI (\emph{U}niform \emph{R}esource \emph{I}dentifier). RDF also uses URIs to name the properties of resources and the relationships between resources as well as the two ends of the link (this is usually referred to as a ``triple''). Hence, an RDF dataset can be represented as a directed, labeled graph where resources are vertices, and triples are -edges with property or relationship names as edge labels. For more details, please go to \href{https://www.w3.org/RDF/}{RDF Introduction}\\ - -To retrieve and manipulate an RDF graph, W3C also proposes a structured query language, SPARQL (\emph{S}imple \emph{P}rotocol \emph{A}nd \emph{R}DF \emph{Q}uery \emph{L}anguage), to access RDF repository. SPARQL contains capabilities for querying required and optional graph patterns along with their conjunctions and disjunctions. SPARQL also supports aggregation, subqueries, negation, creating values by expressions, extensible value testing, and constraining queries by source RDF graph. Similar to RDF graphs, a SPARQL query can also be modeled as a graph, which is a query graph with some variables. Then, evaluating a SPARQL query is equivalent to finding subgraph (homomorphism) matches of a query graph over an RDF graph. You can have a better understanding of SPARQL at \href{https://www.w3.org/TR/sparql11-query/}{SPARQL Introduction}.\\ - -Although there are some RDF data management systems (like Jena, Virtuoso, Sesame) that store the RDF data in relational systems, few existing systems exploit the native graph pattern -matching semantics of SPARQL. \textbf{Here, we implement a graph-based RDF triple store named gStore, which is a joint research project by Peking University, University of Waterloo and Hong Kong University of Science and Technology. The system is developed and maintained by the database group in Institute of Computer Science and Technology, Peking University, China.} A detailed description of gStore can be found at our papers {[}Zou et al., VLDB 11{]} and {[}Zou et al., VLDB Journal 14{]} in the \hyperref[chapter09]{Publication} chapter. This HELP document includes system installment, usage, API, use cases and FAQ. gStore is a open-source project in github under the BSD license. You are welcome to use gStore, report bugs or suggestions, or join us to make gStore better. It is also allowed for you to build all kinds of applications based on gStore, while respecting our work.\\ - - - -\textbf{Please make sure that you have read \hyperref[chapter18]{Legal Issues} before using gStore.} - -\clearpage - -\part{Start} - -\hyperdef{}{chapter00}{\subsection{Chapter 00: A Quick Tour}\label{chapter00}} -Gstore System(also called gStore) is a graph database engine for managing large graph-structured data, which is open-source and targets at Linux operation systems. The whole project is written in C++, with the help of some libraries such as readline, antlr, and so on. Only source tarballs are provided currently, which means you have to compile the source code if you want to use our system. - -\hyperdef{}{getting-started}{\subsubsection{Getting -Started}\label{getting-started}} - -This system is really user-friendly and you can pick it up in several minutes. Remember to check your platform where you want to run this system by viewing \hyperref[chapter01]{System Requirements}. After all are verified, please get this project's source code. There are several ways to do this: - -\begin{itemize} -\item - download the zip from this repository and extract it -\item - fork this repository in your github account -\item - type \texttt{git\ clone\ git@github.com:Caesar11/gStore.git} in your - terminal or use git GUI to acquire it -\end{itemize} - -Then you need to compile the project, just type \texttt{make} in the gStore root directory, and all executables will be ok. To run gStore, please type \texttt{bin/gbuild\ database\_name\ dataset\_path} to build a database named by yourself. And you can use \texttt{bin/gquery\ database\_name} command to query a existing database. What is more, \texttt{bin/gconsole} is a wonderful tool designed for you, providing all operations you need to use gStore. -Notice that all commands should be typed in the root directory of gStore. - -\emph{A detailed description can be found at Chapter 04 -\hyperref[chapter04]{How to use} in this document.} - -\hyperdef{}{advanced-help}{\subsubsection{Advanced -Help}\label{advanced-help}} - -If you want to understand the details of the gStore system, or you want to try some advanced operations(for example, using the API, server/client), please see the chapters below. - -\begin{itemize} -\item - \hyperref[chapter02]{Basic Introduction}: introduce the theory and features of gStore -\item - \hyperref[chapter03]{Install Guide}: instructions on how to install this system -\item - \hyperref[chapter04]{How To Use}: detailed information about using the gStore system -\item - \hyperref[chapter05]{Socket API Explanation}: guide you to develop applications based on our Socket API -\item - \hyperref[chapter06]{HTTP API Explanation}: guide you to develop applications based on our HTTP API -\item - \hyperref[chapter08]{Project Structure}: show the whole structure and sequence of this project -\item - \hyperref[chapter09]{Publications}: contain essays and publications - related with gStore -\item - \hyperref[chapter10]{Update Logs}: keep the logs of the system updates -\item - \hyperref[chapter15]{Test Result}: present the test results of a series of experiments -\end{itemize} - -\hyperdef{}{other-business}{\subsubsection{Other Business}\label{other-business}} - -We have written a series of short essays addressing recurring challenges in using gStore to realize applications, which are placed in -\hyperref[chapter12]{Recipe Book}. - -You are welcome to report any advice or errors in the github Issues part of this repository, if not requiring in-time reply. However, if you want to urgent on us to deal with your reports, please email to to submit your suggestions and report bugs to us by emailing to . A full list of our whole team is in \hyperref[chapter13]{Contributors}. - -There are some restrictions when you use the current gStore project, you can see them on \hyperref[chapter10]{Limitations}. - -Sometimes you may find some strange phenomena(but not wrong case), or something hard to understand/solve(don't know how to do next), then do not hesitate to visit the \hyperref[chapter11]{Frequently Asked Questions} page. - -Graph database engine is a new area and we are still trying to go further. Things we plan to do next is in \hyperref[chapter16]{Future Plan} chapter, and we hope more and more people will support or even -join us. You can support in many ways: - -\begin{itemize} -\item - watch/star our project -\item - fork this repository and submit pull requests to us -\item - download and use this system, report bugs or suggestions -\item - \ldots{} -\end{itemize} - -People who inspire us or contribute to this project will be listed in the \hyperref[chapter17]{Thanks List} chapter. - -\clearpage - -\hyperdef{}{chapter01}{\subsection{Chapter 01: System Requirements}\label{chapter01}} - -\emph{We have tested on linux server with CentOS 6.2 x86\_64 and CentOS 6.6 x86\_64. The version of GCC should be 4.4.7 or later.} - -\begin{longtable}[c]{@{}ll@{}} -\toprule -Item & Requirement\tabularnewline -\midrule -\endhead -operation system & Linux, such as CentOS, Ubuntu and so on\tabularnewline -architecture & x86\_64\tabularnewline -disk size & according to size of dataset\tabularnewline -memory size & according to size of dataset\tabularnewline -glibc & version \textgreater{}= 2.14\tabularnewline -gcc & version \textgreater{}= 4.4.7\tabularnewline -g++ & version \textgreater{}= 4.4.7\tabularnewline -make & need to be installed\tabularnewline -boost & version >= 1.54\tabularnewline -readline & need to be installed\tabularnewline -readline-devel & need to be installed\tabularnewline -openjdk & needed if using Java api\tabularnewline -openjdk-devel & needed if using Java api\tabularnewline -realpath & needed if using gconsole\tabularnewline -ccache & optional, used to speed up the compilation\tabularnewline -\bottomrule -\caption{software requirement} -\end{longtable} - -NOTICE: - -\begin{enumerate} -\item - The name of some packages may be different in different platforms, just install the corresponding one in your own operation system. -\item - To install readline and readline-devel, just type \texttt{dnf\ install\ readline-devel} in Redhat/CentOS/Fedora, or \texttt{apt-get\ install\ libreadline-dev} in Debian/Ubuntu. Please use corresponding commands in other systems. If you use ArchLinux, just type \texttt{pacman\ -S\ readline} to install the readline and readline-devel.(so do other packages) -\item - You do not have to install realpath to use gStore, but if you want to use the gconsole for its convenience, please do so by using \texttt{dnf\ install\ realpath} or \texttt{apt-get\ install\ realpath}. -\item - Our programs use regEx functions, which are provided by GNU/Linux by default. -\item - ANTLR3.4 is used in gStore to produce lexer and parser code for SPARQL query. However, you do not need to install the corresponding antlr libraries because we have merged the libantlr3.4 in our system. -\item - When you type \texttt{make} in the root directory of the gStore project, the Java api will also be compiled. You can modify the makefile if you do not have JDK in your system. However, you are advised to install openjdk-devel in your Linux system. -\item - To install ccache, you need to add epel repository if using CentOS, while in Ubuntu you can directly install it by 'apt-get install ccache' comand. If you can not install ccahe(or maybe you do not want to), please go to modify the makefile(just change the CC variable to g++). -\item If you need to use the HTTP server in gStore, then Boost Library(like boost-devel, including boost headers for developing) must be installed and the version should not be less than 1.54. Remember to check the makefile for your installed path of Boost. -\item - Any other questions, please go to \hyperref[chapter11]{FAQ} page. -\end{enumerate} - -\clearpage - -\hyperdef{}{chapter02}{\subsection{Chapter 02: Basic Introduction}\label{chapter02}} - -\textit{The first essay to come up with Gstore System is -\href{run:../pdf/gStoreVLDBJ.pdf}{gStore\_VLDBJ}, and you can find related publications in -\hyperref[chapter09]{Publications}.} - -\hyperdef{}{what-is-gstore}{\subsubsection{What Is -gStore}\label{what-is-gstore}} - -gStore is a graph-based RDF data management system(or what is commonly called a ``triple store'') that maintains the graph structure of the original \href{http://www.w3.org/TR/rdf11-concepts/}{RDF} data. Its data model is a labeled, directed multi edge graph, where each vertex corresponds to a subject or an object. - -We represent a given \href{http://www.w3.org/TR/sparql11-overview/}{SPARQL} query by a query graph Q. Query processing involves finding subgraph matches of Q over the RDF graph G, instead of joining tables in relational data management system. gStore incorporates an index over the RDF graph (called VS-tree) to speed up query processing. VS-tree is a height balanced tree with a number of associated pruning techniques to speed up subgraph matching. - -\textbf{The gStore project is supported by the National Science Foundation of China (NSFC), Natural Sciences and Engineering Research Council (NSERC) of Canada, and Hong Kong RGC.} - -\hyperdef{}{why-gstore}{\subsubsection{Why gStore}\label{why-gstore}} - -After a series of test, we analyse and keep the result in \hyperref[chapter15]{Test Results}. gStore runs faster to answer complicated queries(for example, contain circles) than other database systems. For simple queries, both gStore and other database systems work -well. - -In addition, now is the big data era and more and more structured data is coming, while the original relational database systems(or database systems based on relational tables) cannot deal with them efficiently. In contrast, gStore can utilize the features of graph data structures, and improve the performance. - -What is more, gStore is a high-extensible project. Many new ideas of graph database have be proposed, and most of them can be used in gStore. For example, our group is also designing a distributed gstore system, which is expected to be released at the end of 2016. - -\hyperdef{}{open-source}{\subsubsection{Open Source}\label{open-source}} - -The gStore source code is available as open-source code under the BSD license. You are welcome to use gStore, report bugs or suggestions, or join us to make gStore better. It is also allowed for you to build all kinds of applications based on gStore, while respecting our work. - -\clearpage - -\hyperdef{}{chapter03}{\subsection{Chapter 03: Install Guide}\label{chapter03}} - -You are advised to read init.conf file, and modify it as you wish. (this file will configure the basic options of gStore system) - -gStore is a green software, and you just need to compile it with one command. Please run \texttt{make} in the gStore root directory to compile the gStore code, link the ANTLR lib, and build executable ``gbuild'', ``gquery'', ``gserver'', ``gclient'', ``gconsole''. What is more, the api of gStore is also built now. - -If you want to use API examples of gStore, please run \texttt{make\ APIexample} to compile example codes for both C++ API and Java API. For details of API, please visit \hyperref[chapter05]{API} chapter. - -Use \texttt{make\ clean} command to clean all objects, executables, and use \texttt{make\ dist} command to clean all objects, executables, libs, datasets, databases, debug logs, temp/text files in the gStore root directory. - -You are free to modify the source code of gStore and create your own project while respecting our work, and type \texttt{make\ tarball} command to compress all useful files into a .tar.gz file, which is easy to carry. - -Type \texttt{make\ gtest} to compile the gtest program if you want to use this test utility. You can see the \hyperref[chapter04]{HOW TO USE} for details of gtest program. - -\clearpage - -\hyperdef{}{chapter04}{\subsection{Chapter 04: How To Use}\label{chapter04}} - -\textit{gStore currently includes five executables and others.} - -\textbf{All the commands of gStore should be used in the root directory of gStore like bin/gconsole, because executables are placed in bin/, and they may use some files whose paths are indicated in the code, not absolute paths. We will ensure that all paths are absolute later by asking users to give the absolute path in their own systems to really install/configure the gStore. However, you must do as we told now to avoid errors.} - -\hyperdef{}{0-gconsole}{\paragraph{0. gconsole}\label{0-gconsole}} - -gconsole is the main console of gStore, which integrates with all functions to operate on gStore, as well as some system commands. Completion of commands name, line editing features and access to the history list are all provided. Feel free to try it, and you may have a wonderful tour!(spaces or tabs at the beginning or end is ok, and no need to type any special characters as separators) - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gconsole -Gstore Console(gconsole), an interactive shell based utility to communicate with -gStore repositories. -usage: start-gconsole [OPTION] --h,--help print this help --s,--source source the SPARQL script -For bug reports and suggestions, see https://github.com/Caesar11/gStore - -notice that commands are a little different between native mode and remote mode! -now is in native mode, please type your commands. -please do not use any separators in the end. - -gstore>help - -gstore>help drop -drop Drop a database according to the given path. - -gstore>connect 127.0.0.1 3305 -now is in remote mode, please type your commands. - -server>disconnect -now is in native mode, please type your commands. - -gstore>build lubm_10 ./data/LUBM_10.n3 -... -import RDF file to database done. - -gstore>unload - -gstore>load lubm_10 -... -database loaded successfully! - -gstore>show -lubm_10 - -gstore>query ./data/LUBM_q0.sql -... -final result is : -?x - - - - - - - - - - - - - - - - -gstore>query "select distinct ?x ?y where { ?x - . -?x ?y . ?y . }" -final result is : -?x ?y -[empty result] - -gstore>unload - -gstore>quit -\end{verbatim} - -Just type \texttt{bin/gconsole} in the root directory of gStore to use this console, and you will find a \texttt{gstore\textgreater{}} prompt, which indicates that you are in native mode and can type in native commands now. There are another mode of this console, which is called remote mode. Just type \texttt{connect} in the native mode to enter the remote mode, and type \texttt{disconnect} to exit to native mode.(the console connect to a gStore server whose ip is `127.0.0.1' and port is 3305, you can specify them by type \texttt{connect\ gStore\_server\_ip\ gStore\_server\_port}) - -You can use \texttt{help} or \texttt{?} either in native mode or remote mode to see the help information, or you can type \texttt{help\ command\_name} or \texttt{?\ command\_name} to see the information of a given command. Notice that there are some differences between the commands in native mode and commands in remote mode. For example, system commands like \texttt{ls}, \texttt{cd} and \texttt{pwd} are provided in native mode, but not in remote mode. Also take care that not all commands contained in the help page are totally achieved, and we may change some functions of the console in the future. - -What we have done is enough to bring you much convenience to use gStore, just enjoy it! - -\hyperdef{}{1-gbuild}{\paragraph{1. gbuild}\label{1-gbuild}} - -gbuild is used to build a new database from a RDF triple format file. - -\texttt{bin/gbuild\ db\_name\ rdf\_triple\_file\_path} - -For example, we build a database from LUBM\_10.n3 which can be found in -example folder. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gbuild LUBM10 ./data/LUBM_10.n3 -gbuild... -argc: 3 DB_store:LUBM10 RDF_data: ./data/LUBM_10.n3 -begin encode RDF from : ./data/LUBM_10.n3 ... -\end{verbatim} - -\hyperdef{}{2-gquery}{\paragraph{2. gquery}\label{2-gquery}} - -gquery is used to query an existing database with files containing -SPARQL queries.(each file contains exact one SPARQL query) - -Type \texttt{bin/gquery\ db\_name\ query\_file} to execute the SPARQL -query retrieved from query\_file in the database named db\_name. - -Use \texttt{bin/gquery\ -\/-help} for detail information of gquery -usage. - -To enter the gquery console, type \texttt{bin/gquery\ db\_name}. The -program shows a command prompt(``gsql\textgreater{}''), and you can type -in a command here. Use \texttt{help} to see basic information of all -commands, while \texttt{help\ command\_t} shows details of a specified -command. - -Type \texttt{quit} to leave the gquery console. - -For \texttt{sparql} command, input a file path which contains a single -SPARQL query. (\emph{answer redirecting to file is supported}) - -When the program finish answering the query, it shows the command prompt -again. - -\emph{gStore2.0 only support simple ``select'' queries(not for -predicates) now.} - -We also take LUBM\_10.n3 as an example. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gquery LUBM10 -gquery... -argc: 2 DB_store:LUBM10/ -loadTree... -LRUCache initial... -LRUCache initial finish -finish loadCache -finish loadEntityID2FileLineMap -open KVstore -finish load -finish loading -Type `help` for information of all commands -Type `help command_t` for detail of command_t -gsql>sparql ./data/LUBM_q0.sql -... ... -Total time used: 4ms. -final result is : - - - - - - - - - - - - - - - -\end{verbatim} - -Notice: - -\begin{itemize} -\item - ``{[}empty result{]}'' will be printed if no answer, and there is an - empty line after all results. -\item - readline lib is used, so you can use arrow key in your keyboard to see - command history, and use and arrow key to move and modify your entire - command. -\item - path completion is supported for utility. (not built-in command - completion) -\end{itemize} - -\hyperdef{}{3-ghttp}{\paragraph{3. ghttp}\label{3-ghttp}} - -ghttp is a daemon. It should be launched first when accessing gStore by HTTP protocol. It uses port 9000. - -Just type \texttt{bin/ghttp} to start server. After the server is started, you can access it by visit the url in a browser or use the Restful API in your program. You can press Ctrl-C to stop the server. (Multiple connections are supported in HTTP server) - -\begin{verbatim} -[bookug@localhost gStore]$ bin/ghttp -the current settings are as below: -key : value ------------------------------------------------------------ -BackupTime : 2000 # 4 am (GMT+8) -buffer_maxium : 100 -db_home : . -db_suffix : .db -debug_level : simple -gstore_mode : single -operation_logs : true -thread_maxium : 1000 - -enter initialize. -server port: 9000 database name: - -\end{verbatim} - -URL rules are listed blow: - -parameters: operation, db\_name, ds\_path, format, sparql - -NOTICE: do URL encoding before sending it to database server. - -operation: build, load, unload, query, monitor, show, checkpoint -\begin{itemize} - \item - db\_name: the name of database, like lubm - \item - format: html, json, txt, csv - \item - sparql: select ?s where { ?s ?p ?o . } - \item - ds\_path in the server: like /home/data/test.n3 -\end{itemize} - -Examples: - -\begin{itemize} - \item - to build a database from a dataset:\\ - http://localhost:9000/?operation=build\&db\_name=[db\_name]\&ds\_path=[ds\_path] - \item - to load a database:\\ - http://localhost:9000/?operation=load\&db\_name=[db\_name] - \item - to query a database:\\ - http://localhost:9000/?operation=query\&format=[format]\&sparql=[sparql] - \item - to unload a database:\\ - http://localhost:9000/?operation=unload\&db\_name=[db\_name] - \item - to monitor the server:\\ - http://localhost:9000/?operation=monitor - \item - to show the database used:\\ - http://localhost:9000/?operation=show - \item - to save the database currently:\\ - http://localhost:9000/?operation=checkpoint -\end{itemize} - - -\hyperdef{}{4-gserver}{\paragraph{4. gserver}\label{4-gserver}} - -gserver is a daemon. It should be launched first when accessing gStore -by gclient or API. It communicates with client through socket. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gserver -s -Server started at port 3305 -\end{verbatim} - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gserver -t -Server stopped at port 3305 -\end{verbatim} - -You can also assign a custom port for listening. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gserver -p 3307 -Port changed to 3307. -\end{verbatim} - -Notice: Multiple threads are not supported by gserver. If you start up -gclient in more than one terminal in the same time, gserver will go -down. - -\hyperdef{}{5-gclient}{\paragraph{5. gclient}\label{5-gclient}} - -gclient is designed as a client to send commands and receive feedbacks. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gclient -ip=127.0.0.1 port=3305 -gsql>help -help - print commands message -quit - quit the console normally -import - build a database for a given dataset -load - load an existen database -unload - unload an existen database -sparql - load query from the second argument -show - show the current database's name -gsql>import lubm data/LUBM_10.n3 -import RDF file to database done. -gsql>load lubm -load database done. -gsql>sparql "select ?s ?o where { ?s ?o . }" -[empty result] - -gsql>quit -\end{verbatim} - -You can also assign gserver's ip and port. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gclient 172.31.19.15 3307 -ip=172.31.19.15 port=3307 -gsql> -\end{verbatim} - -We can use these following commands now: - -\begin{itemize} -\item - \texttt{help} shows the information of all commands -\item - \texttt{import\ db\_name\ rdf\_triple\_file\_name} build a database - from RDF triple file -\item - \texttt{load\ db\_name} load an existing database -\item - \texttt{unload\ db\_name} unload database, but will not delete it on - disk, you can load it next time -\item - \texttt{sparql\ "query\_string"} query the current database with a - SPARQL query string(quoted by ``'') -\item - \texttt{show} displays the name of the current loaded database -\end{itemize} - -Notice: - -\begin{itemize} -\item - at most one database can be loaded in the gclient console -\item - you can place ` ' or `\textbackslash{}t' between different parts of - command, but not use characters like `;' -\item - you should not place any space or tab ahead of the start of any - command -\end{itemize} - -\hyperdef{}{6-test-utilities}{\paragraph{6. test -utilities}\label{6-test-utilities}} - -A series of test program are placed in the test/ folder, and we will -introduce the two useful ones: gtest.cpp and full\_test.sh - -\textbf{gtest is used to test gStore with multiple datasets and -queries.} - -To use gtest utility, please type \texttt{make\ gtest} to compile the -gtest program first. Program gtest is a test tool to generate structural -logs for datasets. Please type \texttt{./gtest\ -\/-help} in the working -directory for details. - -\textbf{Please change paths in the test/gtest.cpp if needed.} - -You should place the datasets and queries in this way: - -\begin{verbatim} -DIR/WatDiv/database/*.nt - -DIR/WatDiv/query/*.sql -\end{verbatim} - -Notice that DIR is the root directory where you place all datasets -waiting to be used by gtest. And WatDiv is a class of datasets, as well -as LUBM. Inside WatDiv(or LUBM, etc. please place all datasets(named -with .nt) in a database/ folder, and place all queries(corresponding to -datasets, named with .sql) in a query folder. - -Then you can run the gtest program with specified parameters, and the -output will be sorted into three logs in gStore root directory: -load.log/(for database loading time and size), time.log/(for query time) -and result.log/(for all query results, not the entire output strings, -but the information to record the selected two database systems matched -or not). - -All logs produced by this program are in TSV format(separated with -`\textbackslash{}t'), you can load them into Calc/Excel/Gnumeric -directly. Notice that time unit is ms, and space unit is kb. - -\textbf{full\_test.sh is used to compare the performance of gStore and -other database systems on multiple datasets and queries.} - -To use full\_test.sh utility, please download the database system which -you want to tats and compare, and set the exact position of database -systems and datasets in this script. The name strategy should be the -same as the requirements of gtest, as well as the logs strategy. - -Only gStore and Jena are tested and compared in this script, but it is -easy to add other database systems, if you would like to spend some time -on reading this script. You may go to -\href{run:../pdf/gstore���Ա���.pdf}{test -report} or \hyperref[chapter11]{Frequently Asked Questions} for help if -you encounter a problem. - -\hyperdef{}{7-gadd}{\paragraph{7. gadd}\label{7-gadd}} - -gadd is used to add triples in a file to an existing database. - -Usage: \texttt{bin/gadd db\_name rdf\_triple\_file\_path}. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gadd lubm ./data/LUBM\_10.n3 -... -argc: 3 DB_store:lubm insert file:./data/LUBM_10.n3 -get important pre ID -... -insert rdf triples done. -inserted triples num: 99550 -\end{verbatim} - -\hyperdef{}{8-gsub}{\paragraph{8. gsub}\label{8-gsub}} - -gsub is used to remove triples from an existing database. - -Usage: \texttt{bin/gsub db\_name rdf\_triple\_file\_path}. - -\begin{verbatim} -[bookug@localhost gStore]$ bin/gsub lubm data/LUBM\_10.n3 -... -argc: 3 DB_store:lubm remove file: data/LUBM\_10.n3 -... -remove rdf triples done. -removed triples num: 99550 -\end{verbatim} - -\hyperdef{}{9-gmonitor}{\paragraph{9. gmonitor}\label{9-gmonitor}} - -After starting ghttp, go into gStore/bin/ and type \texttt{./gmonitor ip port} to check current status of gStore. - -\begin{verbatim} -[bookug@localhost bin]$ ./gmonitor 127.0.0.1 9000 -parameter: ?operation=monitor -request: http://127.0.0.1:9000/%3Foperation%3Dmonitor -null--->[HTTP/1.1 200 OK] -Content-Length--->[127] -database: lubm -triple num: 99550 -entity num: 28413 -literal num: 0 -subject num: 14569 -predicate num: 17 -connection num: 7 -\end{verbatim} - -\hyperdef{}{10-gshow}{\paragraph{10. gshow}\label{10-gshow}} - -After starting ghttp, go into gStore/bin and type \texttt{./gshow ip port} to check loaded database. - -\begin{verbatim} -[bookug@localhost gStore]$ ./gshow 127.0.0.1 9000 -parameter: ?operation=show -request: http://127.0.0.1:9000/%3Foperation%3Dshow -null--->[HTTP/1.1 200 OK] -Content-Length--->[4] -lubm -\end{verbatim} - -\clearpage - -\part{Advanced} - -\hyperdef{}{chapter05}{\subsection{Chapter 05: Socket API Explanation}\label{chapter05}} - -\textbf{This Chapter guides you to use socket API for accessing gStore, which can be used when the server runs gserver. We also provide HTTP API for ghttp, please see \hyperref[chapter06]{【HTTP API Explanation】}.} - -\hyperdef{}{easy-examples}{\subsubsection{Easy -Examples}\label{easy-examples}} - -We provide JAVA, C++, PHP and Python API for gStore now. Please refer to example -codes in \texttt{api/socket/cpp/example}, \texttt{api/socket/java/example}, \texttt{api/socket/php} and \texttt{api/socket/python/example}. To use the four examples to have a try, please ensure that executables have already been generated. Otherwise, for Java and C++, just type \texttt{make\ APIexample} in the root directory of gStore to compile the codes, as well as API. - -Next, \textbf{start up a gStore server by using \texttt{./gserver} -command.} It is ok if you know a running usable gStore server and try to -connect to it, but notice that \textbf{the server ip and port of server -and client must be matched.}(you don't need to change any thing if using -examples, just by default) Then, for Java and C++ code, you need to compile the example codes -in the directory gStore/api/socket/. We provide a utility to do this, and you -just need to type \texttt{make\ APIexample} in the root directory of -gStore. Or you can compile the codes by yourself, in this case please go -to gStore/api/socket/cpp/example/ and gStore/api/socket/java/example/, respectively. - -Finally, go to the example directory and run the corresponding -executables. For C++, just use \texttt{./example} command to run it. And -for Java, use \texttt{make\ run} command or \texttt{java\ -cp\ ../lib/GstoreJavaAPI.jar:.\ JavaAPIExample} to run -it. For PHP, use \texttt{php ./PHPAPIExample}. For python, use \texttt{python ./PythonAPIExample}. All these four executables will connect to a specified gStore server -and do some load or query operations. Be sure that you see the query -results in the terminal where you run the examples, otherwise please go -to \hyperref[chapter11]{Frequently Asked Questions} for help or report -it to us.(the report approach is described in -\hyperref[chapter00]{README}) - -You are advised to read the example code carefully, as well as the -corresponding Makefile. This will help you to understand the API, -specially if you want to write your own programs based on the API -interface. - -\hyperdef{}{api-structure}{\subsubsection{API structure}\label{api-structure}} - -The API of gStore is placed in api/socket/ directory in the root directory of -gStore, whose contents are listed below: - -\begin{itemize} -\item - gStore/api/socket/ - - \begin{itemize} - \item - cpp/ (the C++ API) - - \begin{itemize} - \item - src/ (source code of C++ API, used to build the - lib/libgstoreconnector.a) - - \begin{itemize} - \item - GstoreConnector.cpp (interfaces to interact with gStore server) - \item - GstoreConnector.h - \item - Makefile (compile and build lib) - \end{itemize} - \item - lib/ (where the static lib lies in) - - \begin{itemize} - \item - .gitignore - \item - libgstoreconnector.a (only exist after compiled, you need to - link this lib when you use the C++ API) - \end{itemize} - \item - example/ (small example program to show the basic idea of using - the C++ API) - - \begin{itemize} - \item - CppAPIExample.cpp - \item - Makefile - \end{itemize} - \end{itemize} - \item - java/ (the Java API) - - \begin{itemize} - \item - src/ (source code of Java API, used to build the - lib/GstoreJavaAPI.jar) - - \begin{itemize} - \item - jgsc/GstoreConnector.java (the package which you need to import when you use the Java API) - \item - Makefile (compile and build lib) - \end{itemize} - \item - lib/ - - \begin{itemize} - \item - .gitignore - \item - GstoreJavaAPI.jar (only exist after compiled, you need to - include this JAR in your class path) - \end{itemize} - \item - example/ (small example program to show the basic idea of using - the Java API) - - \begin{itemize} - \item - JavaAPIExample.cpp - \item - Makefile - \end{itemize} - \end{itemize} - - \item - php/ (the PHP API) - - \begin{itemize} - \item - GstoreConnector.php (source code of PHP API, you need to include this file when you use the PHP API) - - \item - PHPAPIExample.php (small example program to show the basic idea of using the PHP API) - \end{itemize} - - \item - python/ (the Python API) - \begin{itemize} - \item - src/ (source code of Python API) - \begin{itemize} - \item - GstoreConnector.py (the package which you need to import when you use the Python API) - \end{itemize} - \item - example/ (small example program to show the basic idea of using the Python API) - \begin{itemize} - \item - PythonAPIExample.py - \end{itemize} - \end{itemize} - - \end{itemize} -\end{itemize} - -\hyperdef{}{c-api}{\subsubsection{C++ API}\label{c-api}} - -\hyperdef{}{interface}{\paragraph{Interface}\label{interface}} - -To use the C++ API, please place the phrase -\texttt{\#include\ "GstoreConnector.h"} in your cpp code. Functions in -GstoreConnector.h should be called like below: - -\begin{verbatim} -// initialize the Gstore server's IP address and port. -GstoreConnector gc("127.0.0.1", 3305); -// build a new database by a RDF file. -// note that the relative path is related to gserver. -gc.build("LUBM10", "example/LUBM_10.n3"); -// then you can execute SPARQL query on this database. -std::string sparql = "select ?x where \ -{\ -?x . \ -?y . \ -?x ?y. \ -?z ?y. \ -?z . \ -?z ?w. \ -?w . \ -}"; -std::string answer = gc.query(sparql); -// unload this database. -gc.unload("LUBM10"); -// also, you can load some exist database directly and then query. -gc.load("LUBM10"); -// query a SPARQL in current database -answer = gc.query(sparql); -\end{verbatim} - -The original declaration of these functions are as below: - -\begin{verbatim} -GstoreConnector(); -GstoreConnector(string _ip, unsigned short _port); -GstoreConnector(unsigned short _port); -bool load(string _db_name); -bool unload(string _db_name); -bool build(string _db_name, string _rdf_file_path); -string query(string _sparql); -\end{verbatim} - -Notice: - -\begin{enumerate} -\item - When using GstoreConnector(), the default value for ip and port is - 127.0.0.1 and 3305, respectively. -\item - When using build(), the rdf\_file\_path(the second parameter) should - be related to the position where gserver lies in. -\item - Please remember to unload the database you have loaded, otherwise - things may go wrong.(the errors may not be reported!) -\end{enumerate} - -\hyperdef{}{compile}{\paragraph{Compile}\label{compile}} - -You are advised to see gStore/api/socket/cpp/example/Makefile for instructions on how to compile your code with the C++ API. Generally, what you must do is compile your own code to object with header in the C++ API, and link the object with static lib in the C++ API. - -Let us assume that your source code is placed in test.cpp, whose position is \$\{GSTORE\}/gStore/.(if using devGstore as name instead of gStore, then the path is \$\{GSTORE\}/devGstore/ directory first: - -\begin{quote} -Use \texttt{g++\ -c\ -I\$\{GSTORE\}/gStore/api/socket/cpp/src/\ test.cpp\ -o\ test.o} to compile your test.cpp into test.o, relative API header is placed in api/socket/cpp/src/. - -Use \texttt{g++\ -o\ test\ test.o\ -L\$\{GSTORE\}/gStore/api/socket/cpp/lib/\ -lgstoreconnector} to link your test.o with the libgstoreconnector.a(a static lib) in api/socket/cpp/lib/. -\end{quote} - -Then you can type \texttt{./test} to execute your own program, which uses our C++ API. It is also advised for you to place relative compile commands in a Makefile, as well as other commands if you like. - -\hyperdef{}{java-api}{\subsubsection{Java API}\label{java-api}} - -\hyperdef{}{interface-1}{\paragraph{Interface}\label{interface-1}} - -To use the Java API, please place the phrase -\texttt{import\ jgsc.GstoreConnector;} in your java code. Functions in -GstoreConnector.java should be called like below: - -\begin{verbatim} -// initialize the Gstore server's IP address and port. -GstoreConnector gc = new GstoreConnector("127.0.0.1", 3305); -// build a new database by a RDF file. -// note that the relative path is related to gserver. -gc.build("LUBM10", "example/LUBM_10.n3"); -// then you can execute SPARQL query on this database. -String sparql = "select ?x where " + "{" + -"?x . " + -"?y . " + -"?x ?y. " + -"?z ?y. " + -"?z . " + -"?z ?w. " + -"?w . " + -"}"; -String answer = gc.query(sparql); -//unload this database. -gc.unload("LUBM10"); -//also, you can load some exist database directly and then query. -gc.load("LUBM10");// query a SPARQL in current database -answer = gc.query(sparql); -\end{verbatim} - -The original declaration of these functions are as below: - -\begin{verbatim} -GstoreConnector(); -GstoreConnector(string _ip, unsigned short _port); -GstoreConnector(unsigned short _port); -bool load(string _db_name); -bool unload(string _db_name); -bool build(string _db_name, string _rdf_file_path); -string query(string _sparql); -\end{verbatim} - -Notice: - -\begin{enumerate} -\item - When using GstoreConnector(), the default value for ip and port is - 127.0.0.1 and 3305, respectively. -\item - When using build(), the rdf\_file\_path(the second parameter) should - be related to the position where gserver lies in. -\item - Please remember to unload the database you have loaded, otherwise - things may go wrong.(the errors may not be reported!) -\end{enumerate} - -\hyperdef{}{compile-1}{\paragraph{Compile}\label{compile-1}} - -You are advised to see gStore/api/socket/java/example/Makefile for instructions on how to compile your code with the Java API. Generally, what you must do is compile your own code to object with jar file in the Java API. - -Let us assume that your source code is placed in test.java, whose position is \$\{GSTORE\}/gStore/.(if using devGstore as name instead of gStore, then the path is \$\{GSTORE\}/devGstore/ directory first: - -\begin{quote} -Use \texttt{javac\ -cp\ \$\{GSTORE\}/gStore/api/socket/java/lib/GstoreJavaAPI.jar\ test.java} to compile your test.java into test.class with the GstoreJavaAPI.jar(a jar package used in Java) in api/socket/java/lib/. -\end{quote} - -Then you can type \texttt{java\ -cp\ \$\{GSTORE\}/gStore/api/socket/java/lib/GstoreJavaAPI.jar:.\ test} to execute your own program(notice that the ``:.'' in command cannot be neglected), which uses our Java API. It is also advised for you to place relative compile commands in a Makefile, as well as other commands if you like. - -\hyperdef{}{php-api}{\subsubsection{PHP API}\label{php-api}} - - \hyperdef{}{interface-2}{\paragraph{Interface}\label{interface-2}} - - To use the PHP API, please place the phrase -\texttt{include('GstoreConnector,php');} in your php code. Functions in -GstoreConnector.php should be called like below: - - \begin{verbatim} - // initialize the Gstore server's IP address and port. - $gc = new Connector("127.0.0.1", 3305); - // build a new database by a RDF file. - // note that the relative path is related to gserver. - $gc->build("LUBM10", "example/LUBM_10.n3"); - // then you can execute SPARQL query on this database. - $sparql = "select ?x where " + "{" + - "?x . " + - "?y . " + - "?x ?y. " + - "?z ?y. " + - "?z . " + - "?z ?w. " + - "?w . " + - "}"; - $answer = gc->query($sparql); - //unload this database. - $gc->unload("LUBM10"); - //also, you can load some exist database directly and then query. - $gc->load("LUBM10");// query a SPARQL in current database - $answer = gc->query(sparql); - \end{verbatim} - - The original declaration of these functions are as below: - - \begin{verbatim} - class Connector { - public function __construct($host, $port); - public function send($data); - public function recv(); - public function build($db_name, $rdf_file_path); - public function load($db_name); - public function unload($db_name); - public function query($sparql); - public function __destruct(); - } - \end{verbatim} - - Notice: - - \begin{enumerate} - \item - When using Connector(), the default value for ip and port is - 127.0.0.1 and 3305, respectively. - \item - When using build(), the rdf\_file\_path(the second parameter) should - be related to the position where gserver lies in. - \item - Please remember to unload the database you have loaded, otherwise - things may go wrong.(the errors may not be reported!) - \end{enumerate} - - \hyperdef{}{run-2}{\paragraph{Run}\label{run-2}} - - You can see gStore/api/socket/php/PHPAPIExample for instructions on how to use PHP API. PHP script doesn't need compiling. You can run PHP file directly or use it in your web project. - - -\hyperdef{}{python-api}{\subsubsection{Python API}\label{python-api}} - - \hyperdef{}{interface-3}{\paragraph{Interface}\label{interface-3}} - - To use the Python API, please place the phrase \texttt{from GstoreConnector import GstoreConnector} in your python code. Functions in GstoreConnector.py should be called like below: - - \begin{verbatim} - // initialize the Gstore server's IP address and port. - gc = GstoreConnector('127.0.0.1', 3305) - // build a new database by a RDF file. - // note that the relative path is related to gserver. - gc.build('LUBM10', 'data/LUBM_10.n3') - // then you can execute SPARQL query on this database. - $sparql = "select ?x where " + "{" + - "?x . " + - "?y . " + - "?x ?y. " + - "?z ?y. " + - "?z . " + - - "?z ?w. " + - "?w . " + - "}"; - answer = gc.query(sparql) - //unload this database. - gc.unload('LUBM10') - //also, you can load some exist database directly and then query. - gc.load('LUBM10')// query a SPARQL in current database - answer = gc.query(sparql) - \end{verbatim} - - The original declaration of these functions are as below: - - \begin{verbatim} - class GstoreConnector { - def _connect(self) - def _disconnect(self) - def _send(self, msg): - def _recv(self) - def _pack(self, msg): - def _communicate(f): - def __init__(self, ip='127.0.0.1', port=3305): - @_communicate - def test(self) - @_communicate - def load(self, db_name) - @_communicate - def unload(self, db_name) - @_communicate - def build(self, db_name, rdf_file_path) - @_communicate - def drop(self, db_name) - @_communicate - def stop(self) - @_communicate - def query(self, sparql) - @_communicate - def show(self, _type=False) - } - \end{verbatim} - - Notice: - - \begin{enumerate} - \item - When using GstoreConnector(), the default value for ip and port is - 127.0.0.1 and 3305, respectively. - \item - When using build(), the rdf\_file\_path(the second parameter) should - be related to the position where gserver lies in. - \item - Please remember to unload the database you have loaded, otherwise - things may go wrong.(the errors may not be reported!) - \end{enumerate} - - \hyperdef{}{run-3}{\paragraph{Run}\label{run-3}} - - You are advised to see gStore/api/socket/python/example/PythonAPIExample for examples on how to use python API. Python file doesn't need compiling, and you can run it directly. - -\clearpage - - -\hyperdef{}{chapter06}{\subsection{Chapter 06: HTTP API Explanation}\label{chapter06}} - -\textbf{This chapter provides API for ghttp. Compared with socket API, HTTP API is more stable and more standard, and can maintain connection. Socket API can not guaratee correct transmission, so the network transmission is faster.} - -\hyperdef{}{easy-http-examples}{\subsubsection{Easy Examples}\label{easy-http-examples}} - -We provide JAVA and C++ API for ghttp now. Please see \texttt{api/http/cpp} and \texttt{api/http/java}. To use these examples, please make sure that executables have already been generated. - -Next, \textbf{start up ghttp service by using \texttt{./ghttp} command.} It is ok if you know a running usable ghttp server and try to connect to it. (you don't need to change anything if using -examples, just by default) Then, for Java and C++ code, you need to compile the example codes in the directory gStore/api/http/. We provide a utility to do this, and you just need to type \texttt{make\ APIexample} in the root directory of gStore. Or you can compile the codes by yourself, in this case please go to gStore/api/http/cpp/ and gStore/api/http/java/, respectively. - -Finally, go to the example directory and run the corresponding executables. All these four executables will connect to a specified ghttp server and do some load or query operations. Be sure that you see the query results in the terminal where you run the examples, otherwise please go to \hyperref[chapter11]{Frequently Asked Questions} for help or report it to us.(the report approach is described in \hyperref[chapter00]{README}) - -You are advised to read the example code carefully, as well as the corresponding Makefile. This will help you to understand the API, specially if you want to write your own programs based on the API interface. - -\hyperdef{}{http-api-structure}{\subsubsection{API Structure}\label{http-api-structure}} - -The HTTP API of gStore is placed in api/http/ directory in the root directory of gStore, whose contents are listed below: - -\begin{itemize} - \item - gStore/api/http/ - - \begin{itemize} - \item - cpp/ （C++ API） - - \begin{itemize} - \item - client.cpp （source code of C++ API） - \item - client.h - \item - example.cpp (example program to show the basic idea of using the C++ API) - \item - Makefile （compile） - - \end{itemize} - - \item - java/ （Java API） - \begin{itemize} - \item - src/ (source code of Java API, used to build the - lib/GstoreJavaAPI.jar) - - \begin{itemize} - \item - jgsc/GstoreConnector.java (the package which you need to import when you use the Java API) - \item - Makefile (compile and build lib) - \end{itemize} - \item - lib/ - - \begin{itemize} - \item - .gitignore - \item - GstoreJavaAPI.jar (only exist after compiled, you need to - include this JAR in your class path) - \end{itemize} - \item - example/ (small example program to show the basic idea of using - the Java API) - - \begin{itemize} - \item - JavaAPIExample.cpp - \item - Makefile - \end{itemize} - \end{itemize} - - \end{itemize} -\end{itemize} - -\hyperdef{}{http-c-api}{\subsubsection{C++ API}\label{http-c-api}} - -\hyperdef{}{http-interface}{\paragraph{Interface}\label{http-interface}} - - -To use the C++ API, please place the phrase \texttt{\#include\ "Client.h"} in your cpp code. Functions in Client.h should be called like below: - -\begin{verbatim} -CHttpClient hc; -string res; -int ret; -// build a new database by a RDF file. -ret = hc.Get("127.0.0.1:9000/build/lumb/data/LUBM_10.n3", res); -cout< . " + -"?y . " + -"?x ?y. " + -"?z ?y. " + -"?z . " + -"?z ?w. " + -"?w . " + -"}"; -String answer = gc.query(sparql); -//unload this database. -gc.unload("LUBM10"); -//also, you can load some exist database directly and then query. -gc.load("LUBM10");// query a SPARQL in current database -answer = gc.query(sparql); -gc.unload("LUBM10"); -\end{verbatim} - -The original declaration of these functions are as below: - -\begin{verbatim} -GstoreConnector(); -GstoreConnector(int _port); -GstoreConnector(String _ip, int _port); -boolean load(String _db_name); -boolean unload(String _db_name); -boolean build(String _db_name, String _rdf_file_path); -boolean drop(String _db_name); -String query(String _sparql); -String show(); -String show(boolean _type); -\end{verbatim} - -\clearpage - - -\hyperdef{}{chapter07}{\subsection{Chapter 07: Use gStore in Web}\label{chapter07}} - - \textbf{This Chapter provides a specific example on how to use our API in a web project.} - - \hyperdef{}{example}{\subsubsection{Example}\label{example}} - - Now you have the basic idea on how to use our APIs to connect gStore. Yet you might be still a little confused. Here we provide a simple demo to show you what to do explicitly. - - Let's say, you need to use gStore in a web project. PHP is a popular general-purpose scripting language that is especially suited to web development. So, using our PHP API can meet your requirements. Here is what we implement: http://59.108.48.18/Gstore/form.php. - - First, get your web server ready so it can run PHP files. We won't give detailed instructions on this step here. You can easily google it according to your web server(for example, Apache or Nginx, etc.) - - Next, go to your web document root(usually in /var/www/html or apache/htdocs, you can check it in config file), and create a folder named "Gstore". Then copy the GstoreConnector.php file into it. Create a "PHPAPI.php" file. Edit it like below: - - \begin{verbatim} - load($dbname); - $query = new Connector($host, $port); - $result = $query->query($sparql); - switch ($format) { - case 1: - $array = explode("<", $result); - $html = '"; - for ($i = 1; $i < count($array); $i++) { - $href = str_replace(">", "", $array[$i]); - $html.= ''; - } - $html.= '
' . - $array[0] . "
' . - $href . '
'; - echo $html; - exit; - - case 2: - $filename = 'result.txt'; - header("Content-Type: application/octet-stream"); - header('Content-Disposition: attachment; - filename="' . $filename . '"'); - echo $result; - exit; - - case 3: - $filename = 'result.csv'; - header("Content-Type: application/octet-stream"); - header('Content-Disposition: attachment; - filename="' . $filename . '"'); - $array = explode("<", $result); - echo $array[0]; - for ($i = 1; $i < count($array); $i++) { - $href = str_replace(">", "", $array[$i]); - echo $href; - } - exit; - } - ?> - \end{verbatim} - - This PHP file get three parametres from a website, including databasename, sparql and output format. Then it use our PHP API to connect gStore and run the query. Finally, the "switch" part gives the output. - - After that, we need a website to collect those imformation(databasename, sparql and output format). We create a html file and use a form to do it, just like below: - \begin{verbatim} -
-
-

Gstore SPARQL Query Editor

-

-
-
    -
  • - -
    - - -
    -
    • - -
  • - -
    - -
    -
    • - -
  • - -
    - -
    - -
  • - - -
    • -
-
- \end{verbatim} - - As you can see in the code, we use a element to get the databasename, and for sparql, - - - - -
  • - -
    - -
    -
    • - -
  • - -
    - -
    - -
  • - - -
    • - - -\end{verbatim} - -你可以在代码中看到，我们用元素得到数据库名，得到sparql，