path: root/src/org/gnunet/construct/Construct.java

/*
 This file is part of GNUnet.
 (C) 2011, 2012 Christian Grothoff (and other contributing authors)

 GNUnet is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published
 by the Free Software Foundation; either version 3, or (at your
 option) any later version.

 GNUnet is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with GNUnet; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.
 */

package org.gnunet.construct;

import org.gnunet.construct.parsers.*;
import org.grothoff.Runabout;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.lang.annotation.Annotation;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.nio.ByteBuffer;
import java.util.*;


/*
Wanted syntax (not fully implemented yet)
- @(U)Int<n> => signed or unsigned fixnum, represented by n bits
- @NestedMessage => nested message
- @FillWith @(U)Int<n> => fill the rest of the message with the specified fixnum, annotation valid on primitive arrays
- @FillWith @NestedMessage => fill the rest of the message with the specified fixnum, annotation valid on message arrays
 of the wanted type
- @VariableSizeArray(lengthField = "<field>") => same syntax as @FillWith
- @FixedSizeArray(length = n) => same syntax as @FillWith
- @Double / @Float => floating point number, should also work with the array annotations
- @FrameSize => specifies the fixnum that determines the containing frame's size
- @ZeroTerminatedString => self-explanatory
- @Constructable => annotation on a class that implements the ConstructableMessage interface,
 providing methods to serialize/unserialize itself.
*/


/**
 * Parse and write the binary representation of java classes, as defined by org.gnunet.construct.*-Annotations
 * on their members.
 *
 * @author Christian Grothoff
 * @author Florian Dold
 */
@SuppressWarnings("unchecked")
public class Construct {
    private static final Logger logger = LoggerFactory
            .getLogger(Construct.class);


    private static HashMap<Class<? extends Message>, Parser> parserCache = new HashMap<Class<? extends Message>,
            Parser>(100);

    /**
     * Information the root of the parser, if the target is nested in another message.
     */
    private static class ParserContext {
        List<Field> parserPath = new ArrayList<Field>();
        // fully determined by parserPath
        ArrayList<Field> frameSizePath = new ArrayList<Field>();

        @Override
        public boolean equals(Object other) {
            // parsers with an equal parserPath also always have the same frameSizePath
            return this.parserPath.equals(((ParserContext) other).parserPath);
        }

        @Override
        public int hashCode() {
            return parserPath.hashCode();
        }
    }

    private static class RootedParser {
        // null if target itself is root
        ParserContext root;
        Parser parser;
    }


    /**
     * Given a byte buffer with a message, parse it into an object of type c. The
     * fields of the class are expected to be annotated with annotations from
     * the construct package.
     *
     * @param srcBuf buffer with the serialized binary data
     * @param c      desired object type to return
     * @return instance of the desired object type
     */
    public static <T extends Message> T parseAs(ByteBuffer srcBuf, Class<T> c) {
        T m = ReflectUtil.justInstantiate(c);

        getParser(c).parse(srcBuf, 0, m, m);

        return m;
    }

    public static <T extends Message> T parseAs(byte[] srcBuf, Class<T> c) {
        return parseAs(ByteBuffer.wrap(srcBuf), c);
    }

    /**
     * Create a Parser for a sub-class of Message. The result is always cached.
     *
     * @param c annotated sub-class of message
     * @return a parser
     */
    public static Parser getParser(Class<? extends Message> c) {

        if (parserCache.containsKey(c)) {
            return parserCache.get(c);
        }

        Parser p = getParser(c, new ParserGenerator());

        parserCache.put(c, p);

        return p;
    }

    private static List<Field> getMessageFields(Class c) {
        LinkedList<Field> fields = new LinkedList<Field>(Arrays.asList(c.getDeclaredFields()));
        while ((c = c.getSuperclass()) != null && Message.class.isAssignableFrom(c)) {
            // fields of the superclass have to be parsed *before* the subclass
            fields.addAll(0, Arrays.asList(c.getDeclaredFields()));
        }
        return fields;
    }

    private static Parser getParser(Class<? extends Message> c,
                                    final ParserGenerator pg) {


        SequenceParser parser = new SequenceParser();

        if (!Modifier.isPublic(c.getModifiers())) {
            throw new AssertionError(String.format("Construct Message %s not declared public", c));
        }

        for (Field f : getMessageFields(c)) {
            pg.c = c;
            Annotation[] as = f.getAnnotations();
            if (as.length == 0 || f.isSynthetic() || Modifier.isStatic(f.getModifiers())) {
                continue;
            }
            if (!Modifier.isPublic(f.getModifiers())) {
                throw new AssertionError(String.format("Field %s of Message %s not declared public", f, c));
            }
            pg.field = f;
            pg.annotations = as;
            pg.annotationsIdx = 0;

            pg.visitAppropriate(as[0]);

            parser.add(pg.parser);
        }

        return parser;
    }

    public static Parser getParser(Class cls, List<Field> frameSizePath, List<Field> pathFromRoot) {
        ParserGenerator pg = new ParserGenerator();
        pg.frameSizePath = new ArrayList<Field>(frameSizePath);
        pg.path = new ArrayList<Field>(pathFromRoot);
        return getParser(cls, pg);
    }

    // has to be public, accessed by Runabout (todo: can we do something about this scope issue?)

    @SuppressWarnings("UnusedDeclaration")
    public static class ParserGenerator extends Runabout {

        // the field we are currently generating a parser for
        Field field;
        // all annotations on the field
        Annotation[] annotations;
        // the index of the annotation we are supposed to process right now
        int annotationsIdx;

        // the message class for which the parser is generated
        Class c;

        // the parser we are actually generating, used by the caller, set as
        // return value of
        // the runabout invocation
        Parser parser;

        // where are we currently, seen from the root message object
        List<Field> path = new LinkedList<Field>();

        // path of the object that has a frame size field
        List<Field> frameSizePath;

        private ParserGenerator() {
        }

        private static List<Field> getFieldPathFromString(final String p, final Class root) {
            Class current = root;

            String[] components = p.split("[.]");

            List<Field> fp = new ArrayList<Field>(components.length);
            for (String member : components) {
                Field f;
                try {
                    f = current.getField(member);
                } catch (NoSuchFieldException e) {
                    throw new AssertionError("invalid field path, component " + member + " not found");
                }

                fp.add(f);

                current = f.getType();
            }

            return fp;

        }

        public void visit(Union u) {
            parser = new UnionParser(frameSizePath, u.optional(),
                    (Class<MessageUnion>) field.getType(),
                    getFieldPathFromString(u.tag(), c), field, path);
        }

        public void visit(FrameSize ts) {

            frameSizePath = new LinkedList<Field>(path);
            frameSizePath.add(field);

            if (annotationsIdx != 0) {
                throw new AssertionError(
                        "FrameSize must be the first annotation on a Field");
            }

            annotationsIdx++;
            if (annotationsIdx >= annotations.length) {
                throw new AssertionError(
                        "FrameSize must be followed by an numeric parser");
            }
            visitAppropriate(annotations[annotationsIdx]);

        }

        public void visit(UInt8 i) {
            parser = new IntegerParser(1, IntegerParser.UNSIGNED, field);
        }

        public void visit(UInt16 i) {
            parser = new IntegerParser(2, IntegerParser.UNSIGNED, field);
        }

        public void visit(UInt32 i) {
            parser = new IntegerParser(4, IntegerParser.UNSIGNED, field);
        }

        public void visit(UInt64 i) {
            parser = new IntegerParser(8, IntegerParser.UNSIGNED, field);
        }

        public void visit(Int8 i) {
            parser = new IntegerParser(1, IntegerParser.SIGNED, field);
        }

        public void visit(Int16 i) {
            parser = new IntegerParser(2, IntegerParser.SIGNED, field);
        }

        public void visit(Int32 i) {
            parser = new IntegerParser(4, IntegerParser.SIGNED, field);
        }

        public void visit(Int64 i) {
            parser = new IntegerParser(8, IntegerParser.SIGNED, field);
        }


        public void visit(ZeroTerminatedString zts) {
            parser = new StringParser(zts.charset(), zts.optional(), field);
        }

        public void visit(IntegerFill i) {
            parser = new IntegerFillParser(frameSizePath, field, i.signed(), i.bitSize() / 8);
        }

        public void visit(NestedMessage n) {
            if (!Message.class.isAssignableFrom(field.getType())) {
                throw new AssertionError("@NestedMessage only works on messages, " + field.getType()
                        + " is not a message (origin: " + c + ")");
            }

            Field nestedField = field;

            if (n.newFrame()) {
                ParserGenerator pg = new ParserGenerator();
                Parser p = getParser((Class<Message>) nestedField.getType(), pg);

                parser = new NestedParser(p, pg.frameSizePath, n.optional(), nestedField, true);

            } else {
                Field old_f = field;
                List<Field> old_path = new ArrayList<Field>(path);
                Class old_c = c;

                path.add(field);

                Parser p = getParser((Class<Message>) nestedField.getType(), this);

                path = old_path;
                c = old_c;
                LinkedList<Field> copy = frameSizePath == null ? null : new LinkedList<Field>(frameSizePath);

                parser = new NestedParser(p, copy, n.optional(), old_f, false);
            }
        }

        public void visit(ByteFill bf) {
            if (frameSizePath == null) {
                throw new AssertionError(
                        "no total size found before variable size element");
            }

            parser = new ByteFillParser(frameSizePath, field);
        }


        public void visit(FixedSizeArray fsa) {
            Field f = field;
            int elemNumber = fsa.length();

            //noinspection unchecked
            getParser((Class<? extends Message>) field.getType()
                    .getComponentType(), this);

            parser = new FixedSizeArrayParser(elemNumber, parser, f);
        }

        public void visit(FixedSizeByteArray fsba) {
            Field f = field;
            int elemNumber = fsba.length();

            parser = new FixedSizeByteArrayParser(elemNumber, f);
        }

        public void visit(Double d) {
            if (!field.getType().equals(java.lang.Double.TYPE)) {
                throw new AssertionError("@Double target must be a primitive 'double' field");
            }
            parser = new DoubleParser(field);
        }

        public void visit(FillWith fw) {
            Field f = field;
            Class old_c = c;

            Parser p = getParser((Class<? extends Message>) field.getType()
                    .getComponentType(), this);

            parser = new FillParser(p, frameSizePath, f);
        }

        public void visit(VariableSizeArray vsa) {
            Field f = field;
            Class old_c = c;


            Parser p = getParser((Class<? extends Message>) field.getType()
                    .getComponentType(), this);

            try {
                parser = new VariableSizeArrayParser(p, old_c.getField(vsa
                        .lengthField()), f);

            } catch (SecurityException e) {
                throw new AssertionError(
                        String.format(
                                "VariableSizeArray: length field '%s' not declared public",
                                vsa.lengthField()));
            } catch (NoSuchFieldException e) {
                throw new AssertionError(String.format(
                        "VariableSizeArray: length field '%s' does not exist in class %s",
                        vsa.lengthField(), old_c));
            }
        }

        /*
         * We override this to improve the error message, otherwise obfuscated by internal java proxy objects
         */
        @Override
        public void visitDefault(Object obj) {
            if (obj instanceof Annotation) {
                Annotation ann = (Annotation) obj;
                throw new AssertionError("invalid Construct annotation: " + ann.annotationType().getName());
            } else {
                throw new AssertionError();
            }
        }
    }

    /**
     * Serialize a given message object to a binary byte array. The fields of
     * the object are expected to be annotated with annotations from the
     * construct package.
     *
     * @param dstBuf where to write the binary object data
     * @param msg    object to serialize
     * @return number of bytes written to data, -1 on error
     */
    public static int write(ByteBuffer dstBuf, Message msg) {
        Parser p = getParser(msg.getClass());
        return p.write(dstBuf, msg);
    }

    /**
     * Compute the size of a serialized message.
     *
     * @param m object to serialize
     * @return number of bytes required, -1 on error
     */
    public static int getSize(Message m) {
        if (m == null) {
            return 0;
        }
        Parser p = getParser(m.getClass());
        return p.getSize(m);
    }

    public static byte[] toBinary(Message m) {
        byte[] a = new byte[getSize(m)];
        ByteBuffer buf = ByteBuffer.wrap(a);
        write(buf, m);
        return a;
    }

    public static void patch(Message m) {
        Parser p = getParser(m.getClass());
        p.patch(m, p.getSize(m), m);
    }

}