+ initial load of the application server project

LICENSE.TXT

@@ -0,0 +1,3 @@
+These software source code resources are distributed under the
+terms of the MIT License.
+http://opensource.org/licenses/MIT

README.TXT

@@ -0,0 +1,76 @@
+Haiku Depot Server
+~~~~~~~~~~~~~~~~~~
+
+This collection of files represents the source code for the "Haiku Depot Server"; a web-services and HTML environment for working with Haiku packages.  This is a maven java project that primarily builds an application server.
+
+---
+REQUIREMENTS, BUILD AND SETUP
+
+To build and use this software, you will require;
+
+* Java JDK 1.6 or better
+* Apache Maven 3.0.3 or better
+* A Postgres 9.1 or better database server
+* An internet connection
+
+On a debian 7 host, the following packages can be installed;
+
+  apt-get install default-jdk
+  apt-get install maven
+  apt-get install postgresql postgresql-client
+
+The project consists of a number of modules.  The "haikudepotserver-webapp" is the application server module.  This module requires a database in order to function.  It is expecting to work with a Postgres database server.  Create a blank postgres database and ensure that you are able to access the database over an internet socket authenticating as some user.  You can leave the database devoid of schema objects for now because the application server will populate necessary schema objects on the first launch.
+
+The following file in the "haikudepotserver-webapp" is a template configuration file for the application server;
+
+  src/main/resources/local-sample.properties
+
+Copy this to an adjacent file in the same directory called "local.properties".  You will need to edit properties starting with "jdbc..." in order to let the application server know how to access your postgres database.
+
+The first build will take longer than 'normal' because it will need to download a number of dependencies from the internet in order to undertake the build.  Some downloads are related to web-resources.  These downloads are only indirectly managed by the maven build process.  For this reason, your first step should be to complete a command-line build by issuing the following command in the same directory as this file;
+
+  mvn package
+
+This step will ensure that the web-resources are populated.  You should now be able to either continue to use the project in the command line environment or you can switch to use a java IDE.
+
+To start-up the application server for development purposes, issue the following command from the same top level of the project; the same directory as this file.
+
+  mvn org.apache.tomcat.maven:tomcat7-maven-plugin:2.1:run
+
+This may take some time to start-up; especially the first time.  Once it has started-up, it should be possible to connect to the application server using the following URL;
+
+  http://localhost:8080/
+
+There won't be any repositories or data loaded, and because of this, it is not possible to view any data.  Now a repository can be added to obtain packages from.  Open a SQL terminal and add a repository;
+
+  INSERT INTO
+    haikudepot.repository (
+      id, active, create_timestamp, modify_timestamp,
+      architecture_id, code, url)
+    VALUES (
+      nextval('haikudepot.repository_seq'), true, now(), now(),
+      (SELECT id FROM haikudepot.architecture WHERE code='x86'), 'test', 'file:///tmp/repo.hpkr');
+
+This artificial repository will obtain a file from the local file system's temporary directory.  You could, for example, take the test HPKR file supplied in the test resources of the "haikudepotserver-packagefile" module and place this at /tmp/repo.hpkr.  Now it should be possible to prompt the system to take-up the repository data by dispatching a URL of this form using a tool such as curl;
+
+  curl "http://localhost:8080/importrepositorydata?code=test"
+
+You should now refresh your browser and it ought to be possible to view the packages that have been imported from the test file.
+
+---
+API
+
+The API for communicating with the server is described in the "haikudepotserver-api1" module.  This contains DTO model objects describing the objects to be used in API calls as well as interfaces that describe the API calls that are available.  The application server vends the API as JSON-RPC.  More information about JSON-RPC can be found here;
+
+  http://www.jsonrpc.org/
+
+This API is intended to be used for the single-page web application as well as a desktop application.
+
+---
+HPKR HANDLING
+
+Haiku packages are described using HPK* files and these are described here;
+
+  http://dev.haiku-os.org/wiki/PackageManagement
+
+The "haikudepotserver-packagefile" module contains handling for HPKR files.  Given the requirements of the application server this handling is limited to read-only access.

haikudepotserver-api1/pom.xml

@@ -0,0 +1,25 @@
+<project
+        xmlns="http://maven.apache.org/POM/4.0.0"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+    <parent>
+        <artifactId>haikudepotserver-parent</artifactId>
+        <groupId>org.haikuos</groupId>
+        <relativePath>../haikudepotserver-parent</relativePath>
+        <version>1.0.1-SNAPSHOT</version>
+    </parent>
+
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>org.haikuos</groupId>
+    <artifactId>haikudepotserver-api1</artifactId>
+    <packaging>jar</packaging>
+
+    <dependencies>
+        <dependency>
+            <groupId>com.googlecode</groupId>
+            <artifactId>jsonrpc4j</artifactId>
+        </dependency>
+    </dependencies>
+
+</project>

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/CaptchaApi.java

@@ -0,0 +1,30 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1;
+
+import com.googlecode.jsonrpc4j.JsonRpcService;
+import org.haikuos.haikudepotserver.api1.model.captcha.GenerateCaptchaRequest;
+import org.haikuos.haikudepotserver.api1.model.captcha.GenerateCaptchaResult;
+
+/**
+ * <p>This API is to do with captchas.  A captcha is a small image that is shown to a user in order for the user to
+ * supply some textual response from the image in order to verify that the operator is likely to be human and not a
+ * computer.  This helps to prevent machine-hacking of systems.  This API is able to provide a captcha and other
+ * APIs require that a 'captcha response' is supplied as part of a request.  In general a captcha is valid for a
+ * certain length of time.</p>
+ */
+
+@JsonRpcService("/api/v1/captcha")
+public interface CaptchaApi {
+
+    /**
+     * <p>This method will return a captcha that can be used in systems where a captcha response (generated by a
+     * human) is required to be supplied with an API request.</p>
+     */
+
+    GenerateCaptchaResult generateCaptcha(GenerateCaptchaRequest generateCaptchaRequest);
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/MiscellaneousApi.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1;
+
+import com.googlecode.jsonrpc4j.JsonRpcService;
+import org.haikuos.haikudepotserver.api1.model.miscellaneous.GetAllArchitecturesRequest;
+import org.haikuos.haikudepotserver.api1.model.miscellaneous.GetAllArchitecturesResult;
+import org.haikuos.haikudepotserver.api1.model.miscellaneous.GetAllMessagesRequest;
+import org.haikuos.haikudepotserver.api1.model.miscellaneous.GetAllMessagesResult;
+
+@JsonRpcService("/api/v1/miscellaneous")
+public interface MiscellaneousApi {
+
+    /**
+     * <p>This method will return all of the localization messages that might be able to be displayed
+     * to the user from the result of validation problems and so on.</p>
+     */
+
+    GetAllMessagesResult getAllMessages(GetAllMessagesRequest getAllMessagesRequest);
+
+    /**
+     * <P>This method will return a list of all of the possible architectures in the system such as x86 or arm.
+     * Note that this will explicitly exclude the pseudo-architectures of "source" and "any".</p>
+     */
+
+    GetAllArchitecturesResult getAllArchitectures(GetAllArchitecturesRequest getAllArchitecturesRequest);
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/PkgApi.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1;
+
+import com.googlecode.jsonrpc4j.JsonRpcService;
+import org.haikuos.haikudepotserver.api1.model.pkg.GetPkgRequest;
+import org.haikuos.haikudepotserver.api1.model.pkg.GetPkgResult;
+import org.haikuos.haikudepotserver.api1.model.pkg.SearchPkgsRequest;
+import org.haikuos.haikudepotserver.api1.model.pkg.SearchPkgsResult;
+import org.haikuos.haikudepotserver.api1.support.ObjectNotFoundException;
+
+/**
+ * <p>This API is for access to packages and package versions.</p>
+ */
+
+@JsonRpcService("/api/v1/pkg")
+public interface PkgApi {
+
+    /**
+     * <p>This method can be invoked to get a list of all of the packages that match some search critera in the
+     * request.</p>
+     */
+
+    SearchPkgsResult searchPkgs(SearchPkgsRequest request);
+
+    /**
+     * <p>This method will return a package and the specified versions.  It will throw an
+     * {@link org.haikuos.haikudepotserver.api1.support.ObjectNotFoundException} if the package was not able to be located.</p>
+     */
+
+    GetPkgResult getPkg(GetPkgRequest request) throws ObjectNotFoundException;
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/UserApi.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1;
+
+import com.googlecode.jsonrpc4j.JsonRpcService;
+import org.haikuos.haikudepotserver.api1.model.user.*;
+import org.haikuos.haikudepotserver.api1.support.ObjectNotFoundException;
+
+/**
+ * <p>This interface defines operations that can be undertaken around users.</p>
+ */
+
+@JsonRpcService("/api/v1/user")
+public interface UserApi {
+
+    /**
+     * <p>This method will create a user in the system.  It is identified by a username
+     * and authenticated by a password.  The password is supplied in the clear.</p>
+     */
+
+    CreateUserResult createUser(CreateUserRequest createUserRequest);
+
+    /**
+     * <p>This method will get the user identified by the nickname in the request object.
+     * If no user was able to be found an instance of {@link org.haikuos.haikudepotserver.api1.support.ObjectNotFoundException}
+     * is thrown.</p>
+     */
+
+    GetUserResult getUser(GetUserRequest getUserRequest) throws ObjectNotFoundException;
+
+    /**
+     * <p>This method will allow a client to authenticate against the server.  If this is
+     * successful then the client will know that it is OK to use the authentication
+     * principal and credentials for further API calls.</p>
+     */
+
+    AuthenticateUserResult authenticateUser(AuthenticateUserRequest authenticateUserRequest);
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/captcha/GenerateCaptchaRequest.java

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.captcha;
+
+public class GenerateCaptchaRequest {
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/captcha/GenerateCaptchaResult.java

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.captcha;
+
+public class GenerateCaptchaResult {
+
+    /**
+     * <p>This token uniquely identifies the captcha.</p>
+     */
+
+    public String token;
+
+    /**
+     * <p>This is a base-64 encoded image of the captcha.  It could, for example, be used with a data url to render
+     * the image in an "img" tag on a web page.</p>
+     */
+
+    public String pngImageDataBase64;
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/miscellaneous/GetAllArchitecturesRequest.java

@@ -0,0 +1,9 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.miscellaneous;
+
+public class GetAllArchitecturesRequest {
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/miscellaneous/GetAllArchitecturesResult.java

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.miscellaneous;
+
+import java.util.List;
+
+public class GetAllArchitecturesResult {
+
+    public List<Architecture> architectures;
+
+    public static class Architecture {
+        public String code;
+    }
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/miscellaneous/GetAllMessagesRequest.java

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.miscellaneous;
+
+public class GetAllMessagesRequest {
+
+    // add locale here?
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/miscellaneous/GetAllMessagesResult.java

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.miscellaneous;
+
+import java.util.Map;
+
+public class GetAllMessagesResult {
+
+    /**
+     * <p>This is a key-value pair map of the localization messages.</p>
+     */
+
+    public Map<String,String> messages;
+
+}

haikudepotserver-api1/src/main/java/org/haikuos/haikudepotserver/api1/model/pkg/GetPkgRequest.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2013, Andrew Lindesay
+ * Distributed under the terms of the MIT License.
+ */
+
+package org.haikuos.haikudepotserver.api1.model.pkg;
+
+public class GetPkgRequest {
+
+    /**
+     * <p>This type defines the versions that should be sent back in the result.  If the client were
+     * only interested in the latest version for example, then it should use the "LATEST" value.</p>
+     */
+
+    public enum VersionType {
+        LATEST
+    }
+
+    /**
+     * <p>This is the name of the package that you wish to obtain.</p>
+     */
+
+    public String name;
+
+    /**
+     * <P>Only a version of the package for this architecture will be returned.  Note that this also
+     * includes the pseudo-architectures "any" and "source".</P>
+     */
+
+    public String architectureCode;
+
+    public VersionType versionType;
+
+    // TODO - natural language
+
+}