Adds documentation and applies license

teavm-platform/src/main/java/org/teavm/platform/metadata/MetadataGenerator.java

@@ -1,11 +1,65 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
 import org.teavm.model.MethodReference;
 
 /**
+ * <p>Represents a generator, that produces resources during compilation phase. User must implement this
+ * interface and bind this implementation to a method that would read resources at runtime.</p>
+ *
+ * <p>Here is the full workflow:</p>
+ *
+ * <ul>
+ *   <li>Compiler finds a method that is marked with the {@link MetadataProvider} annotation.
+ *       This method must be declared as <code>native</code>, otherwise compiler should throw an exception.</li>
+ *   <li>Compiler instantiates the {@link MetadataGenerator} instance with the no-arg constructor
+ *       If no such constructor exists, compiler throws exception.</li>
+ *   <li>Compiler runs the {@link #generateMetadata(MetadataGeneratorContext, MethodReference)} method
+ *       ands gets the produced resource.</li>
+ *   <li>Compiler generates implementation of the method marked with {@link MetadataProvider}, that
+ *       will return the generated resource in run time.</li>
+ * </ul>
+ *
+ * <p>Therefore, the type of the value, returned by the
+ * {@link #generateMetadata(MetadataGeneratorContext, MethodReference)}
+ * method must match the returning type of the appropriate method, marked with {@link MetadataProvider}.</p>
+ *
+ * <p>The valid resource types are the following:</p>
+ *
+ * <ul>
+ *   <li>Valid interfaces, marked with the {@link Resource} annotation. Read the description of this annotation
+ *       for detailed description about valid resources interfaces.</li>
+ *   <li>{@link ResourceArray} of valid resources.</li>
+ *   <li>{@link ResourceMap} of valid resources.</li>
+ *   <li>{@link String}, {@link Integer}, {@link Byte}, {@link Short}, {@link Float}, {@link Double},
+ *       {@link Boolean}.</li>
+ *   <li>The <code>null</code> value.</li>
+ * </ul>
+ *
+ * <p>All other types are not considered to be resources and therefore are not accepted.</p>
  *
  * @author Alexey Andreev <konsoletyper@gmail.com>
  */
 public interface MetadataGenerator {
+    /**
+     * <p>Generates resources, that will be available at runtime.</p>
+     *
+     * @param context context that contains useful compile-time information.
+     * @param method method which will be used to access the generated resources at run time.
+     */
     Object generateMetadata(MetadataGeneratorContext context, MethodReference method);
 }

teavm-platform/src/main/java/org/teavm/platform/metadata/MetadataGeneratorContext.java

@@ -1,13 +1,59 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
+import java.util.Properties;
 import org.teavm.model.ListableClassReaderSource;
+import org.teavm.vm.TeaVM;
 
 /**
+ * <p>Represents context with compile-time information, that is useful for {@link MetadataGenerator}.
+ * This context is provided by the compiler infrastructure.</p>
  *
  * @author Alexey Andreev <konsoletyper@gmail.com>
  */
 public interface MetadataGeneratorContext {
+    /**
+     * Gets the collection of all classes that were achieved by the dependency checker.
+     */
     ListableClassReaderSource getClassSource();
 
+    /**
+     * Gets the class loader that is used by the compiler.
+     */
+    ClassLoader getClassLoader();
+
+    /**
+     * Gets properties that were specified to {@link TeaVM}.
+     */
+    Properties getProperties();
+
+    /**
+     * Creates a new resource of the given type. The description of valid resources
+     * is available in documentation for {@link Resource}.
+     */
     <T> T createResource(Class<T> resourceType);
+
+    /**
+     * Creates a new resource array.
+     */
+    <T> ResourceArray<T> createResourceArray();
+
+    /**
+     * Creates a new resource map.
+     */
+    <T> ResourceMap<T> createResourceMap();
 }

teavm-platform/src/main/java/org/teavm/platform/metadata/MetadataProvider.java

@@ -1,3 +1,18 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
 import java.lang.annotation.ElementType;
@@ -6,6 +21,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * <p>Binds a {@link MetadataGenerator} to a native method.</p>
  *
  * @author Alexey Andreev <konsoletyper@gmail.com>
  */

teavm-platform/src/main/java/org/teavm/platform/metadata/Resource.java

@@ -1,3 +1,18 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
 import java.lang.annotation.ElementType;
@@ -6,6 +21,13 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
+ * <p>Marks a valid <b>resource interface</b>. Resource interface is an interface, that has get* and set* methods,
+ * according the default convention for JavaBeans. Each property must have both getter and setter.
+ * Also each property's must be either primitive value, except for <code>long</code> or valid resource.</p>
+ *
+ * @see MetadataGenerator
+ * @see ResourceArray
+ * @see ResourceMap
  *
  * @author Alexey Andreev <konsoletyper@gmail.com>
  */

teavm-platform/src/main/java/org/teavm/platform/metadata/ResourceArray.java

@@ -1,3 +1,18 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
 /**

teavm-platform/src/main/java/org/teavm/platform/metadata/ResourceMap.java

@@ -1,3 +1,18 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.metadata;
 
 /**

teavm-platform/src/main/java/org/teavm/platform/plugin/PlatformPlugin.java

@@ -1,3 +1,18 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
 package org.teavm.platform.plugin;
 
 import org.teavm.vm.spi.TeaVMHost;

teavm-platform/src/main/java/org/teavm/platform/plugin/ResourceProxy.java

@@ -0,0 +1,30 @@
+/*
+ *  Copyright 2014 Alexey Andreev.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package org.teavm.platform.plugin;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+
+/**
+ *
+ * @author Alexey Andreev <konsoletyper@gmail.com>
+ */
+class ResourceProxy implements InvocationHandler {
+    @Override
+    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
+        return null;
+    }
+}