# HG changeset patch
# User Matthias Grimmer <grimmer@ssw.jku.at>
# Date 1421239396 -3600
# Node ID d6dba4c723c0f70fdc0efd9e27f70f504e44d489
# Parent  552993e5795adce135129d8e2bf3888d1f3391e7
Interop: improve exception names and JavaDoc

diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/ForeignAccessFactory.java
--- a/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/ForeignAccessFactory.java	Tue Jan 13 19:48:15 2015 +0100
+++ b/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/ForeignAccessFactory.java	Wed Jan 14 13:43:16 2015 +0100
@@ -27,10 +27,30 @@
 import com.oracle.truffle.api.*;
 import com.oracle.truffle.api.interop.messages.*;
 
+/**
+ * Interface of a factory that produces AST snippets that can access a foreign {@code TruffleObject}
+ * . A Truffle language implementation accesses a {@code TruffleObject} via a {@code Message}. The
+ * {@code TruffleObject} instance provides a {@code ForeignAccessFactory} instance that provides an
+ * AST snippet for a given {@code Message}.
+ */
 public interface ForeignAccessFactory {
 
+    /**
+     * Provides a {@code InteropPredicate} that tests whether a {@code TruffleObject} can be
+     * accessed using AST snippets, produced by this {@code ForeignAccessFactory}.
+     *
+     * @return the {@code InteropPredicate} that tests if a {@code TruffleObject} can be accessed by
+     *         AST snipptes, produces by this {@code ForeignAccessFactory}.
+     */
     InteropPredicate getLanguageCheck();
 
+    /**
+     * Provides an AST snippet to access a {@code TruffleObject}.
+     *
+     * @param tree the {@code Message} that represents the access to a {@code TruffleObject}.
+     * @return the AST snippet for accessing the {@code TruffleObject}, wrapped as a
+     *         {@code CallTarget}.
+     */
     CallTarget getAccess(Message tree);
 
 }
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/InteropPredicate.java
--- a/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/InteropPredicate.java	Tue Jan 13 19:48:15 2015 +0100
+++ b/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/InteropPredicate.java	Wed Jan 14 13:43:16 2015 +0100
@@ -24,8 +24,17 @@
  */
 package com.oracle.truffle.api.interop;
 
-//TODO(mg): remove this interface and use java.util.function.Predicate once api.interop can use Java 8
-
+/**
+ * Represents a predicate of a {@code TruffleObject} argument.
+ */
 public interface InteropPredicate {
-    boolean test(Object object);
+
+    /**
+     * Evaluates the predicate on the given {@code TruffleObject}.
+     *
+     * @param object the input argument
+     * @return {@code true} if the {@code TruffleObject} argument matches the predicate, otherwise
+     *         {@code false}
+     */
+    boolean test(TruffleObject object);
 }
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/TruffleObject.java
--- a/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/TruffleObject.java	Tue Jan 13 19:48:15 2015 +0100
+++ b/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/TruffleObject.java	Wed Jan 14 13:43:16 2015 +0100
@@ -25,9 +25,14 @@
 package com.oracle.truffle.api.interop;
 
 /**
- * Interface for Truffle guest language implementations that can be shared across other language
- * implementations.
+ * Interface for any entity of a Truffle guest language implementations that can be shared across
+ * other language implementations.
  */
 public interface TruffleObject {
+    /**
+     * Provides the {@code ForeignAccessFactory} instance for this {@code TruffleObject} instance.
+     *
+     * @return the {@code ForeignAccessFactory} instance for this {@code TruffleObject} instance.
+     */
     ForeignAccessFactory getForeignAccessFactory();
 }
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/AccessException.java
--- a/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/AccessException.java	Tue Jan 13 19:48:15 2015 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,38 +0,0 @@
-/*
- * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code 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
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-package com.oracle.truffle.api.interop.exception;
-
-/**
- * An exception thrown if the receiver of a guest language implementation cannot resolve an access.
- */
-public final class AccessException extends RuntimeException {
-
-    private static final long serialVersionUID = -2014660135608964970L;
-
-    public AccessException(String reason) {
-        super(reason);
-    }
-
-}
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/TypeException.java
--- a/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/TypeException.java	Tue Jan 13 19:48:15 2015 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,34 +0,0 @@
-/*
- * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
- * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
- *
- * This code is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License version 2 only, as
- * published by the Free Software Foundation.  Oracle designates this
- * particular file as subject to the "Classpath" exception as provided
- * by Oracle in the LICENSE file that accompanied this code.
- *
- * This code 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
- * version 2 for more details (a copy is included in the LICENSE file that
- * accompanied this code).
- *
- * You should have received a copy of the GNU General Public License version
- * 2 along with this work; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
- *
- * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
- * or visit www.oracle.com if you need additional information or have any
- * questions.
- */
-package com.oracle.truffle.api.interop.exception;
-
-public class TypeException extends RuntimeException {
-
-    private static final long serialVersionUID = 5786411886196161509L;
-
-    public TypeException(String reason) {
-        super(reason);
-    }
-}
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/UnsupportedMessageException.java
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/UnsupportedMessageException.java	Wed Jan 14 13:43:16 2015 +0100
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code 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
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.api.interop.exception;
+
+/**
+ * An exception thrown if the receiver of a guest language implementation cannot resolve a message.
+ */
+public final class UnsupportedMessageException extends RuntimeException {
+
+    private static final long serialVersionUID = -2014660135608964970L;
+
+    public UnsupportedMessageException(String reason) {
+        super(reason);
+    }
+
+}
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/UnsupportedTypeException.java
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/graal/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/exception/UnsupportedTypeException.java	Wed Jan 14 13:43:16 2015 +0100
@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code 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
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.truffle.api.interop.exception;
+
+/**
+ * An exception thrown if a foreign type cannot be converted to a language-dependent regular type.
+ */
+public class UnsupportedTypeException extends RuntimeException {
+
+    private static final long serialVersionUID = 5786411886196161509L;
+
+    public UnsupportedTypeException(String reason) {
+        super(reason);
+    }
+}
diff -r 552993e5795a -r d6dba4c723c0 graal/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java
--- a/graal/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java	Tue Jan 13 19:48:15 2015 +0100
+++ b/graal/com.oracle.truffle.api.object/src/com/oracle/truffle/api/object/ObjectType.java	Wed Jan 14 13:43:16 2015 +0100
@@ -76,11 +76,11 @@
         return new ForeignAccessFactory() {
 
             public InteropPredicate getLanguageCheck() {
-                throw new AccessException(this.toString() + " cannot be shared");
+                throw new UnsupportedMessageException(this.toString() + " cannot be shared");
             }
 
             public CallTarget getAccess(Message tree) {
-                throw new AccessException(this.toString() + " cannot be shared; Message not possible: " + tree.toString());
+                throw new UnsupportedMessageException(this.toString() + " cannot be shared; Message not possible: " + tree.toString());
             }
         };
     }