src/main/java/net/pterodactylus/sone/freenet/fcp/Command.java

   1 /*
   2  * Sone - Command.java - Copyright © 2011 David Roden
   3  *
   4  * This program is free software: you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation, either version 3 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 package net.pterodactylus.sone.freenet.fcp;
  19
  20 import net.pterodactylus.sone.freenet.SimpleFieldSetBuilder;
  21 import freenet.support.SimpleFieldSet;
  22 import freenet.support.api.Bucket;
  23
  24 /**
  25  * Implementation of an FCP interface for other clients or plugins to
  26  * communicate with Sone.
  27  *
  28  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  29  */
  30 public interface Command {
  31
  32         /**
  33          * Executes the command, returning a reply that will be sent back to the
  34          * requesting plugin.
  35          *
  36          * @param parameters
  37          *            The parameters of the comand
  38          * @param data
  39          *            The data of the command (may be {@code null})
  40          * @param accessType
  41          *            The access type
  42          * @return A reply to send back to the plugin
  43          * @throws FcpException
  44          *             if an error processing the parameters occurs
  45          */
  46         public Response execute(SimpleFieldSet parameters, Bucket data, AccessType accessType) throws FcpException;
  47
  48         /**
  49          * The access type of the request.
  50          *
  51          * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  52          */
  53         public static enum AccessType {
  54
  55                 /** Access from another plugin. */
  56                 DIRECT,
  57
  58                 /** Access via restricted FCP. */
  59                 RESTRICTED_FCP,
  60
  61                 /** Access via FCP with full access. */
  62                 FULL_FCP,
  63
  64         }
  65
  66         /**
  67          * Interface for command replies.
  68          *
  69          * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  70          */
  71         public static class Response {
  72
  73                 /** The message name of the reponse. */
  74                 private final String messageName;
  75
  76                 /** The reply parameters. */
  77                 private final SimpleFieldSet replyParameters;
  78
  79                 /** The reply data, may be {@code null}. */
  80                 private final byte[] data;
  81
  82                 /** The data bucket, may be {@code null}. */
  83                 private final Bucket bucket;
  84
  85                 /**
  86                  * Creates a new reply with the given parameters.
  87                  *
  88                  * @param messageName
  89                  *            The message name
  90                  * @param replyParameters
  91                  *            The reply parameters
  92                  */
  93                 public Response(String messageName, SimpleFieldSet replyParameters) {
  94                         this(messageName, replyParameters, null, null);
  95                 }
  96
  97                 /**
  98                  * Creates a new reply with the given parameters.
  99                  *
 100                  * @param messageName
 101                  *            The message name
 102                  * @param replyParameters
 103                  *            The reply parameters
 104                  * @param data
 105                  *            The data of the reply (may be {@code null})
 106                  */
 107                 public Response(String messageName, SimpleFieldSet replyParameters, byte[] data) {
 108                         this(messageName, replyParameters, data, null);
 109                 }
 110
 111                 /**
 112                  * Creates a new reply with the given parameters.
 113                  *
 114                  * @param messageName
 115                  *            The message name
 116                  * @param replyParameters
 117                  *            The reply parameters
 118                  * @param bucket
 119                  *            The bucket of the reply (may be {@code null})
 120                  */
 121                 public Response(String messageName, SimpleFieldSet replyParameters, Bucket bucket) {
 122                         this(messageName, replyParameters, null, bucket);
 123                 }
 124
 125                 /**
 126                  * Creates a new reply with the given parameters.
 127                  *
 128                  * @param messageName
 129                  *            The message name
 130                  * @param replyParameters
 131                  *            The reply parameters
 132                  * @param data
 133                  *            The data of the reply (may be {@code null})
 134                  * @param bucket
 135                  *            The bucket of the reply (may be {@code null})
 136                  */
 137                 private Response(String messageName, SimpleFieldSet replyParameters, byte[] data, Bucket bucket) {
 138                         this.messageName = messageName;
 139                         this.replyParameters = replyParameters;
 140                         this.data = data;
 141                         this.bucket = bucket;
 142                 }
 143
 144                 /**
 145                  * Returns the reply parameters.
 146                  *
 147                  * @return The reply parameters
 148                  */
 149                 public SimpleFieldSet getReplyParameters() {
 150                         return new SimpleFieldSetBuilder(replyParameters).put("Message", messageName).get();
 151                 }
 152
 153                 /**
 154                  * Returns whether the reply has reply data.
 155                  *
 156                  * @see #getData()
 157                  * @return {@code true} if this reply has data, {@code false} otherwise
 158                  */
 159                 public boolean hasData() {
 160                         return data != null;
 161                 }
 162
 163                 /**
 164                  * Returns the data of the reply.
 165                  *
 166                  * @return The data of the reply
 167                  */
 168                 public byte[] getData() {
 169                         return data;
 170                 }
 171
 172                 /**
 173                  * Returns whether the reply has a data bucket.
 174                  *
 175                  * @see #getBucket()
 176                  * @return {@code true} if the reply has a data bucket, {@code false}
 177                  *         otherwise
 178                  */
 179                 public boolean hasBucket() {
 180                         return bucket != null;
 181                 }
 182
 183                 /**
 184                  * Returns the data bucket of the reply.
 185                  *
 186                  * @return The data bucket of the reply
 187                  */
 188                 public Bucket getBucket() {
 189                         return bucket;
 190                 }
 191
 192         }
 193
 194         /**
 195          * Response implementation that can return an error message and an optional
 196          * error code.
 197          *
 198          * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
 199          */
 200         public class ErrorResponse extends Response {
 201
 202                 /**
 203                  * Creates a new error response with the given message.
 204                  *
 205                  * @param message
 206                  *            The error message
 207                  */
 208                 public ErrorResponse(String message) {
 209                         super("Error", new SimpleFieldSetBuilder().put("ErrorMessage", message).get());
 210                 }
 211
 212                 /**
 213                  * Creates a new error response with the given code and message.
 214                  *
 215                  * @param code
 216                  *            The error code
 217                  * @param message
 218                  *            The error message
 219                  */
 220                 public ErrorResponse(int code, String message) {
 221                         super("Error", new SimpleFieldSetBuilder().put("ErrorMessage", message).put("ErrorCode", code).get());
 222                 }
 223
 224         }
 225
 226 }