xapi.io.service.IOService Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of xapi-dev Show documentation

Everything needed to run a comprehensive dev environment. Just type X_ and pick a service from autocomplete; new dev modules will be added as they are built. The only dev service not included in the uber jar is xapi-dev-maven, as it includes all runtime dependencies of maven, adding ~4 seconds to build time, and 6 megabytes to the final output jar size (without xapi-dev-maven, it's ~1MB).

The newest version!

package xapi.io.service;

import xapi.collect.api.StringDictionary;
import xapi.io.api.IOCallback;
import xapi.io.api.IOMessage;
import xapi.io.api.IORequest;
import xapi.io.api.IORequestBuilder;
import xapi.util.api.ConvertsValue;
import xapi.util.api.RemovalHandler;

public interface IOService {

   IORequestBuilder request(Class classLit, String id);

  /**
   * Registers a de/serializer for a given class literal,
   * and returns a removal method to undo the registration.
   *
   * The ONLY safe way to use the undo method is to
   * a) synchronize(classLit) {
   * b) RemovalHandler r = registerParser(...);
   * try {
   *  // do stuff, but don't try to acquire a lock.
   *  // just send your request and get out.
   *  } finally {
   *  r.remove();// resets the given de/serializer combo.
   *  }
   *
   * Do not keep references of the removal handler beyond the method that
   * called registerParser, unless you are willing to risk indeterminism.
   * We will do check-and-set,
   *
   * Also, for code to work in gwt or other transpiled targets,
   * you MUST be using a class literal, and not a class _REFERENCE_.
   *
   * registerParser(IPojo.class, ...)  - Good!
   *
   * Class theClass = IPojo.class;
   * registerParser(theClass, ...) - Bad!
   *
   * When you use class literals, the reference can be reliably resolved,
   * otherwise it's on you to record every method passing that class lit along,
   * and do something filthy, like stash it in a ThreadLocal<Stack>,.
   *
   * The deal for magically generated code is "pass in the interface you want,
   * get back the best (or only) implementation for your platform.
   *
   * @param classLit - The type to register serializers for.
   * @param serializer - ConvertsValue
   * @param deserializer - ConvertsValue
   * @return - A removal method to undo registration;
   * using this in a try / finally block, in case you just
   * want to borrow the de/serialization process.
   */
   RemovalHandler registerParser(Class classLit,
    ConvertsValue serializer,
    ConvertsValue deserializer);

  void put(String url, byte[] body, StringDictionary headers,
    IOCallback> callback);

  IORequest get(String url, StringDictionary headers,
    IOCallback> callback);

  IORequest post(String url, String body, StringDictionary headers,
    IOCallback> callback);

  void delete(String url, StringDictionary headers,
    IOCallback> callback);

}