You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by ni...@apache.org on 2016/12/17 10:28:16 UTC
[40/81] [abbrv] [partial] zest-java git commit: ZEST-195 ;
Replace all "zest" with "polygene"
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/importer/InstanceImporter.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/importer/InstanceImporter.java b/core/api/src/main/java/org/apache/polygene/api/service/importer/InstanceImporter.java
new file mode 100644
index 0000000..52c38cb
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/importer/InstanceImporter.java
@@ -0,0 +1,64 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.importer;
+
+import java.util.Objects;
+import java.util.stream.Stream;
+import org.apache.polygene.api.injection.scope.Structure;
+import org.apache.polygene.api.service.ImportedServiceDescriptor;
+import org.apache.polygene.api.service.ServiceImporter;
+import org.apache.polygene.api.service.ServiceImporterException;
+import org.apache.polygene.api.structure.Application;
+import org.apache.polygene.api.structure.Layer;
+import org.apache.polygene.api.structure.Module;
+
+/**
+ * Return a predefined service instance that was provided as meta-info. Search for meta-info in the following order:
+ * the service itself, the module of the service, the layer of the service, the whole application.
+ */
+public final class InstanceImporter<T>
+ implements ServiceImporter<T>
+{
+ @Structure
+ private Application application;
+
+ @Structure
+ private Layer layer;
+
+ @Structure
+ private Module module;
+
+ @Override
+ public T importService( final ImportedServiceDescriptor serviceDescriptor )
+ throws ServiceImporterException
+ {
+ return Stream.of( serviceDescriptor, module, layer, application )
+ .flatMap( holder -> serviceDescriptor.types().map( type -> (T) holder.metaInfo( type ) ) )
+ .filter( Objects::nonNull )
+ .findFirst().orElse( null );
+ }
+
+ @Override
+ public boolean isAvailable( T instance )
+ {
+ return true;
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/importer/NewObjectImporter.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/importer/NewObjectImporter.java b/core/api/src/main/java/org/apache/polygene/api/service/importer/NewObjectImporter.java
new file mode 100644
index 0000000..11df2fd
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/importer/NewObjectImporter.java
@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.importer;
+
+import org.apache.polygene.api.injection.scope.Structure;
+import org.apache.polygene.api.object.ObjectFactory;
+import org.apache.polygene.api.service.ImportedServiceDescriptor;
+import org.apache.polygene.api.service.ServiceImporter;
+import org.apache.polygene.api.service.ServiceImporterException;
+
+/**
+ * Import Services using a new registered Object instance.
+ */
+public final class NewObjectImporter<T>
+ implements ServiceImporter<T>
+{
+ @Structure
+ private ObjectFactory obf;
+
+ @Override
+ @SuppressWarnings( "unchecked" )
+ public T importService( ImportedServiceDescriptor serviceDescriptor )
+ throws ServiceImporterException
+ {
+ return obf.newObject( (Class<T>) serviceDescriptor.types().findFirst().orElse( null ));
+ }
+
+ @Override
+ public boolean isAvailable( T instance )
+ {
+ return true;
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceInstanceImporter.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceInstanceImporter.java b/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceInstanceImporter.java
new file mode 100644
index 0000000..b0abf1b
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceInstanceImporter.java
@@ -0,0 +1,79 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.importer;
+
+import org.apache.polygene.api.identity.Identity;
+import org.apache.polygene.api.injection.scope.Structure;
+import org.apache.polygene.api.service.ImportedServiceDescriptor;
+import org.apache.polygene.api.service.ServiceFinder;
+import org.apache.polygene.api.service.ServiceImporter;
+import org.apache.polygene.api.service.ServiceImporterException;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Use a registered service that implements ServiceImporter to do the actual
+ * import. The service id of the service that this importer should delegate to must
+ * be set as meta-info on this service. Example:
+ * <pre><code>
+ * module.services(MyServiceImporterService.class).identifiedBy("someid");
+ * module.importedServices(OtherService.class).importedBy(ServiceInstanceImporter.class).setMetaInfo("someid");
+ * </code></pre>
+ */
+public class ServiceInstanceImporter<T>
+ implements ServiceImporter<T>
+{
+ @Structure
+ ServiceFinder finder;
+
+ ServiceImporter<T> service;
+
+ Identity serviceId;
+
+ @Override
+ public T importService( ImportedServiceDescriptor importedServiceDescriptor )
+ throws ServiceImporterException
+ {
+ serviceId = importedServiceDescriptor.metaInfo( Identity.class );
+
+ return serviceImporter().importService( importedServiceDescriptor );
+ }
+
+ @Override
+ public boolean isAvailable( T instance )
+ {
+ return serviceImporter().isAvailable( instance );
+ }
+
+ @SuppressWarnings( {"raw", "unchecked"} )
+ private ServiceImporter<T> serviceImporter()
+ {
+ if( service == null )
+ {
+ service = finder.findServices( ServiceImporter.class )
+ .filter( ref -> ref.identity().equals( serviceId ) )
+ .findFirst().map( ServiceReference::get )
+ .orElseThrow( () -> new ServiceImporterException(
+ "No service importer with id '" + serviceId + "' was found" )
+ );
+ }
+ return service;
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceSelectorImporter.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceSelectorImporter.java b/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceSelectorImporter.java
new file mode 100644
index 0000000..929b814
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/importer/ServiceSelectorImporter.java
@@ -0,0 +1,75 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.importer;
+
+import java.util.function.Predicate;
+import java.util.stream.Stream;
+import org.apache.polygene.api.injection.scope.Structure;
+import org.apache.polygene.api.service.Availability;
+import org.apache.polygene.api.service.ImportedServiceDescriptor;
+import org.apache.polygene.api.service.ServiceFinder;
+import org.apache.polygene.api.service.ServiceImporter;
+import org.apache.polygene.api.service.ServiceImporterException;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * If several services are available with a given type, and you want to constrain
+ * the current module to use a specific one, then use this importer. Specify a
+ * Specification<ServiceReference<T>> criteria as meta-info for the service, which will be applied
+ * to the list of available services, and the first match will be chosen.
+ *
+ * This importer will avoid selecting itself, as could be possible if the ServiceQualifier.first()
+ * filter is used.
+ */
+public final class ServiceSelectorImporter<T>
+ implements ServiceImporter<T>
+{
+ @Structure
+ private ServiceFinder locator;
+
+ @Override
+ @SuppressWarnings( { "raw", "unchecked" } )
+ public T importService( ImportedServiceDescriptor serviceDescriptor )
+ throws ServiceImporterException
+ {
+ Predicate<ServiceReference<?>> selector = serviceDescriptor.metaInfo( Predicate.class );
+ Class serviceType = serviceDescriptor.types().findFirst().orElse( null );
+
+ Stream<ServiceReference<T>> services = locator.findServices( serviceType );
+ Predicate<ServiceReference<T>> filter = ref ->
+ {
+ Predicate selector1 = ref.metaInfo( Predicate.class );
+ return selector1 == null || selector == selector1;
+ };
+ return services.filter( filter.and( selector ) )
+ .findFirst().map( ServiceReference::get )
+ .orElseThrow(
+ () -> new ServiceImporterException(
+ "Could not find any service to import that matches the given specification for "
+ + serviceDescriptor.identity() ) );
+ }
+
+ @Override
+ public boolean isAvailable( T instance )
+ {
+ return !( instance instanceof Availability ) || ( (Availability) instance ).isAvailable();
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/importer/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/importer/package.html b/core/api/src/main/java/org/apache/polygene/api/service/importer/package.html
new file mode 100644
index 0000000..be1d382
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/importer/package.html
@@ -0,0 +1,24 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~
+ ~
+ -->
+<html>
+ <body>
+ <h2>Service Importers.</h2>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/package.html b/core/api/src/main/java/org/apache/polygene/api/service/package.html
new file mode 100644
index 0000000..c217c9c
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/package.html
@@ -0,0 +1,24 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~
+ ~
+ -->
+<html>
+ <body>
+ <h2>Service API.</h2>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Active.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Active.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Active.java
new file mode 100644
index 0000000..8428f36
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Active.java
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Filter services based on whether they are active or not.
+ * <p>
+ * At an injection point you can do this:
+ * </p>
+ * <pre><code>
+ * @Service @Active MyService service;
+ * </code></pre>
+ * <p>
+ * to get only a service that is currently active.
+ * </p>
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Qualifier( Active.ActiveQualifier.class )
+public @interface Active
+{
+ /**
+ * Active Annotation Qualifier.
+ * See {@link Active}.
+ */
+ public final class ActiveQualifier
+ implements AnnotationQualifier<Active>
+ {
+ @Override
+ public <T> Predicate<ServiceReference<?>> qualifier( Active active )
+ {
+ return ServiceQualifier.whereActive();
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/AnnotationQualifier.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/AnnotationQualifier.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/AnnotationQualifier.java
new file mode 100644
index 0000000..8c35932
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/AnnotationQualifier.java
@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Annotation;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Constructs a Specification for a given qualifier annotation
+ */
+public interface AnnotationQualifier<QUALIFIER extends Annotation>
+{
+ public <T> Predicate<ServiceReference<?>> qualifier( QUALIFIER qualifier );
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Available.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Available.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Available.java
new file mode 100644
index 0000000..7af40d1
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Available.java
@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Filter services based on whether they are available or not.
+ *
+ * At an injection point you can do this:
+ *
+ * <pre><code>
+ * @Service @Available MyService service;
+ * </code></pre>
+ * to get only a service that is currently available.
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Qualifier( Available.AvailableQualifier.class )
+public @interface Available
+{
+ /**
+ * Available Annotation Qualifier.
+ * See {@link Available}.
+ */
+ public final class AvailableQualifier
+ implements AnnotationQualifier<Available>
+ {
+ @Override
+ public <T> Predicate<ServiceReference<?>> qualifier( Available active )
+ {
+ return ServiceQualifier.whereAvailable();
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/HasMetaInfo.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/HasMetaInfo.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/HasMetaInfo.java
new file mode 100644
index 0000000..73d551f
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/HasMetaInfo.java
@@ -0,0 +1,108 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Filter services based on Meta Info being declared on the Service.
+ * <p>
+ * Meta Info of any type can be set on the service during assembly, e.g.;
+ * </p>
+ * <pre><code>
+ * module.addService( MyService.class ).setMetaInfo( new MyCustomInfo(someData) );
+ * </code></pre>
+ * <p>
+ * and then at an injection point you can do this:
+ * </p>
+ * <pre><code>
+ * @Service @HasMetaInfo(MyCustomInfo.class) MyService service;
+ * </code></pre>
+ * <p>
+ * to get only a service that has a MyCustomInfo instance set as meta info.
+ * </p>
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Qualifier( HasMetaInfo.HasMetaInfoQualifier.class )
+@Documented
+public @interface HasMetaInfo
+{
+ /**
+ * The Class(es) needed to have been defined in the Service meta info for a qualifier to evaluate true.
+ *
+ * @return One or more classes that should be defined in the service's meta info for the service to be considered
+ * qualified. If more than one class is defined, the {@code anded()} parameter will define if they must be
+ * AND'ed or OR'ed together.
+ */
+ Class[] value();
+
+ /**
+ * True if the Classes defined in the value() field should be AND'ed instead of OR'ed.
+ *
+ * @return If true, all the Class types defined in {@code value()} must be defined for the service for it to be
+ * qualified. If false, if any of the Class types defined in {@code value()} is defined for the service
+ * the service is qualified.
+ */
+ boolean anded() default false;
+
+ /**
+ * HasMetaInfo Annotation Qualifier.
+ * See {@link HasMetaInfo}.
+ */
+ public static class HasMetaInfoQualifier
+ implements AnnotationQualifier<HasMetaInfo>
+ {
+ @Override
+ public <T> Predicate<ServiceReference<?>> qualifier( final HasMetaInfo hasMetaInfo )
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ @SuppressWarnings( {"raw", "unchecked"} )
+ public boolean test( ServiceReference<?> service )
+ {
+ for( Class metaInfoType : hasMetaInfo.value() )
+ {
+ Object metaInfo = service.metaInfo( metaInfoType );
+ if( hasMetaInfo.anded() )
+ {
+ if( metaInfo == null )
+ {
+ return false;
+ }
+ }
+ else
+ {
+ if( metaInfo != null )
+ {
+ return true;
+ }
+ }
+ }
+ return false;
+ }
+ };
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/IdentifiedBy.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/IdentifiedBy.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/IdentifiedBy.java
new file mode 100644
index 0000000..40c52bb
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/IdentifiedBy.java
@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Filter services based on identity. Identity can be set during assembly, like so:
+ * <pre><code>
+ * module.addService(MyService.class).identifiedBy("myservice1");
+ * </code></pre>
+ *
+ * and then at an injection point you can do this:
+ * <pre><code>
+ * @Service @IdentifiedBy("myservice1") MyService service;
+ * </code></pre>
+ * to get only a service identified "myservice1".
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Qualifier( IdentifiedBy.IdentifiedByQualifier.class )
+public @interface IdentifiedBy
+{
+ public abstract String value();
+
+ /**
+ * IdentifiedBy Annotation Qualifier.
+ * See {@link IdentifiedBy}.
+ */
+ public final class IdentifiedByQualifier
+ implements AnnotationQualifier<IdentifiedBy>
+ {
+ @Override
+ public <T> Predicate<ServiceReference<?>> qualifier( IdentifiedBy identifiedBy )
+ {
+ return ServiceQualifier.withId( identifiedBy.value() );
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Qualifier.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Qualifier.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Qualifier.java
new file mode 100644
index 0000000..c0b183b
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Qualifier.java
@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * Annotation used to declare Qualifiers annotations.
+ */
+@Retention( RetentionPolicy.RUNTIME )
+public @interface Qualifier
+{
+ public abstract Class<? extends AnnotationQualifier> value();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceQualifier.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceQualifier.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceQualifier.java
new file mode 100644
index 0000000..8e6a948
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceQualifier.java
@@ -0,0 +1,113 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * This class helps you select a particular service
+ * from a list.
+ * <p>
+ * Provide a Selector which does the actual
+ * selection from the list. A common case is to select
+ * based on reference of the service, which you can do this way:
+ * </p>
+ *
+ * <pre><code>
+ * new ServiceQualifier<MyService>(services, ServiceQualifier.withId("someId"))
+ * </code></pre>
+ * <p>
+ * Many selectors can be combined by using firstOf. Example:
+ * </p>
+ * <pre><code>
+ * new ServiceQualifier<MyService>(services, firstOf(withTags("sometag"), firstActive(), first()))
+ * </code></pre>
+ * <p>
+ * This will pick a service that has the tag "sometag", or if none is found take the first active one. If no
+ * service is active, then the first service will be picked.
+ * </p>
+ */
+public abstract class ServiceQualifier
+{
+ public static Predicate<ServiceReference<?>> withId( final String anId )
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ public boolean test( ServiceReference<?> service )
+ {
+ return service.identity().toString().equals( anId );
+ }
+ };
+ }
+
+ public static Predicate<ServiceReference<?>> whereMetaInfoIs( final Object metaInfo )
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ public boolean test( ServiceReference<?> service )
+ {
+ Object metaObject = service.metaInfo( metaInfo.getClass() );
+ return metaObject != null && metaInfo.equals( metaObject );
+ }
+ };
+ }
+
+ public static Predicate<ServiceReference<?>> whereActive()
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ public boolean test( ServiceReference<?> service )
+ {
+ return service.isActive();
+ }
+ };
+ }
+
+ public static Predicate<ServiceReference<?>> whereAvailable()
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ public boolean test( ServiceReference<?> service )
+ {
+ return service.isAvailable();
+ }
+ };
+ }
+
+ public static Predicate<ServiceReference<?>> withTags( final String... tags )
+ {
+ return new Predicate<ServiceReference<?>>()
+ {
+ @Override
+ public boolean test( ServiceReference<?> service )
+ {
+ ServiceTags serviceTags = service.metaInfo( ServiceTags.class );
+
+ return serviceTags != null && serviceTags.hasTags( tags );
+ }
+ };
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceTags.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceTags.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceTags.java
new file mode 100644
index 0000000..c616a9f
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/ServiceTags.java
@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.io.Serializable;
+
+/**
+ * Use this as metainfo about a Service to specify tags. Easiest way to set them on a service
+ * is to use the <code>ServiceDeclaration.taggedWith(String...)</code> method.
+ *
+ * These can be used in conjunction with the withTags() Service
+ * Selector.
+ */
+public final class ServiceTags
+ implements Serializable
+{
+ private String[] tags;
+
+ public ServiceTags( String... tags )
+ {
+ this.tags = tags;
+ }
+
+ public String[] tags()
+ {
+ return tags;
+ }
+
+ public boolean hasTag( String tag )
+ {
+ for( String serviceTag : tags )
+ {
+ if( serviceTag.equals( tag ) )
+ {
+ return true;
+ }
+ }
+
+ return false;
+ }
+
+ public boolean hasTags( String... aTags )
+ {
+ for( String tag : aTags )
+ {
+ if( !hasTag( tag ) )
+ {
+ return false;
+ }
+ }
+
+ return true;
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Tagged.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Tagged.java b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Tagged.java
new file mode 100644
index 0000000..3df0780
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/Tagged.java
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.service.qualifier;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.util.function.Predicate;
+import org.apache.polygene.api.service.ServiceReference;
+
+/**
+ * Filter services based on tags. Tags can be set using the ServiceTags meta-info, like so:
+ * <pre><code>
+ * module.addService(MyService.class).taggedWith(new ServiceTags("onetag","twotag"));
+ * </code></pre>
+ *
+ * and then at an injection point you can do this:
+ *
+ * <pre><code>
+ * @Service @Tagged("onetag") MyService service;
+ * </code></pre>
+ * to get only a service tagged with MyService. If several match only the first match is used.
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Qualifier( Tagged.TaggedQualifier.class )
+public @interface Tagged
+{
+ String[] value();
+
+ /**
+ * Tagged Annotation Qualifier.
+ * See {@link Tagged}.
+ */
+ final class TaggedQualifier
+ implements AnnotationQualifier<Tagged>
+ {
+ @Override
+ public Predicate<ServiceReference<?>> qualifier( Tagged tagged )
+ {
+ return ServiceQualifier.withTags( tagged.value() );
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/service/qualifier/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/service/qualifier/package.html b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/package.html
new file mode 100644
index 0000000..d37dc22
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/service/qualifier/package.html
@@ -0,0 +1,62 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~
+ ~
+ -->
+<html>
+ <body>
+ <h2>Service Qualifiers.</h2>
+ <p>
+ The @Service injection is only able to specify the type of the service to be injected. If any other type of
+ qualification has to be done it has to be done manually but for common cases it's more convenient to use
+ annotations to do this filtering. This package contains annotations to perform this qualification.
+ </p>
+ <p>Example:</p>
+ <blockquote>
+ <pre>@Service @Tagged( "sometag" ) MyService service;</pre>
+ </blockquote>
+ <p>
+ This will only inject instances of MyService that have been tagged with "sometag". If none exist an
+ exception will occur at injection time since it is not optional.
+ </p>
+ <p>It also works with iterables:</p>
+ <blockquote>
+ <pre>@Service @Tagged( "sometag" ) Iterable<MyService> services;</pre>
+ </blockquote>
+ <p>
+ The qualification will be evaluated upon each call to iterator(), and since the qualifier has access to a
+ ServiceReference, which contains the isActive() method, it can even provide some dynamicity.
+ </p>
+ <blockquote>
+ <pre>@Service @Active Iterable<SomeImportedService> importedServices;</pre>
+ </blockquote>
+ <p>
+ Let's say these SomeImportedService are only sometimes available. Then whenever iterator() is called the
+ {@link org.apache.polygene.api.service.qualifier.Active} tag can kick in and filter out those whose
+ ServiceReference.isActive() returns false.
+ </p>
+ <p>Standard ones defined in the API are:</p>
+ <ul>
+ <li>{@link org.apache.polygene.api.service.qualifier.Active}</li>
+ <li>{@link org.apache.polygene.api.service.qualifier.Available}</li>
+ <li>{@link org.apache.polygene.api.service.qualifier.HasMetaInfo}</li>
+ <li>{@link org.apache.polygene.api.service.qualifier.IdentifiedBy}</li>
+ <li>{@link org.apache.polygene.api.service.qualifier.Tagged}</li>
+ </ul>
+ <p>See tests and API for more examples, and how to implement your own qualifiers.</p>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/GenericSideEffect.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/GenericSideEffect.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/GenericSideEffect.java
new file mode 100644
index 0000000..7d9119e
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/GenericSideEffect.java
@@ -0,0 +1,63 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.Method;
+
+/**
+ * Base class for generic SideEffects.
+ */
+public abstract class GenericSideEffect
+ extends SideEffectOf<InvocationHandler>
+ implements InvocationHandler
+{
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public Object invoke( final Object proxy, final Method method, final Object[] args )
+ throws Throwable
+ {
+ invoke( method, args );
+ return null;
+ }
+
+ /**
+ * Convenience method to be overridden by subclasses in order to avoid returning null, as returned value from side
+ * effects is not taken in consideration.
+ *
+ * @param method the method that was invoked
+ * @param args the arguments of the method invocation
+ *
+ * @throws Throwable - the exception to throw from the method invocation on the proxy instance. The exception's type
+ * must be assignable either to any of the exception types declared in the throws clause of the
+ * interface method or to the unchecked exception types {code}java.lang.RuntimeException{code}
+ * or {code}java.lang.Error{code}. If a checked exception is thrown by this method that is not
+ * assignable to any of the exception types declared in the throws clause of the interface method,
+ * then an UndeclaredThrowableException containing the exception that was thrown by this method
+ * will be thrown by the method invocation on the proxy instance.
+ */
+ protected void invoke( final Method method, final Object[] args )
+ throws Throwable
+ {
+ }
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectDescriptor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectDescriptor.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectDescriptor.java
new file mode 100644
index 0000000..85a2842
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectDescriptor.java
@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect;
+
+/**
+ * SideEffect Descriptor.
+ */
+public interface SideEffectDescriptor
+{
+ Class<?> modifierClass();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectOf.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectOf.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectOf.java
new file mode 100644
index 0000000..eca348f
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectOf.java
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect;
+
+import org.apache.polygene.api.sideeffect.internal.SideEffectFor;
+
+/**
+ * Base class for SideEffects. It introduces a typed "next" pointer
+ * that SideEffects can use to get the result of the original invocation.
+ * <p>
+ * Generic SideEffects should subclass {@link GenericSideEffect} instead.
+ * </p>
+ * <p>
+ * SideEffects implementations must be thread-safe in their implementation,
+ * as multiple threads may share instances.
+ * </p>
+ */
+public abstract class SideEffectOf<T>
+{
+ final
+ @SideEffectFor
+ protected T result = null;
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffects.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffects.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffects.java
new file mode 100644
index 0000000..af1ab3f
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffects.java
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation is used by composites and mixins to declare what SideEffects
+ * should apply to the type or specific method.
+ */
+@Retention( RetentionPolicy.RUNTIME )
+@Target( { ElementType.TYPE, ElementType.METHOD } )
+@Documented
+public @interface SideEffects
+{
+ Class<?>[] value();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectsDescriptor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectsDescriptor.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectsDescriptor.java
new file mode 100644
index 0000000..55bbcf4
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/SideEffectsDescriptor.java
@@ -0,0 +1,27 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect;
+
+/**
+ * SideEffects Descriptor.
+ */
+public interface SideEffectsDescriptor
+{
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/SideEffectFor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/SideEffectFor.java b/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/SideEffectFor.java
new file mode 100644
index 0000000..59617c8
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/SideEffectFor.java
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.sideeffect.internal;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.apache.polygene.api.injection.InjectionScope;
+
+/**
+ * This annotation is required once in each SideEffect, to mark the
+ * field where the element providing the invocation result should be
+ * injected.
+ * <p>
+ * The type of the field must be of the same type as the SideEffect
+ * itself, or an InvocationHandler.
+ * </p>
+ * <p>
+ * Example;
+ * </p>
+ * <pre><code>
+ * public interface MyStuff
+ * {
+ * SomeResult doSomething();
+ * }
+ *
+ * public class MyStuffSideEffect
+ * implements MyStuff
+ * {
+ * @SideEffectFor MyStuff next;
+ *
+ * public SomeResult doSomething()
+ * {
+ * SomeResult result = next.doSomething();
+ *
+ * // HERE DO THE SIDEEFFECT STUFF.
+ *
+ * return result; // Result value is ignored, null would work too.
+ * }
+ * }
+ * </code></pre>
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.FIELD, ElementType.PARAMETER })
+@Documented
+@InjectionScope
+public @interface SideEffectFor
+{
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/package.html b/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/package.html
new file mode 100644
index 0000000..9f70396
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/internal/package.html
@@ -0,0 +1,28 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~
+ ~
+ -->
+<html>
+ <body>
+ <h1>Internal/Private package for the API.</h1>
+ <p>
+ This is an internal package, and no classes in this package is part of the API and compatibility
+ with these classes will not be attempted.
+ </p>
+ </body>
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/sideeffect/package.html
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/sideeffect/package.html b/core/api/src/main/java/org/apache/polygene/api/sideeffect/package.html
new file mode 100644
index 0000000..4f14cc1
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/sideeffect/package.html
@@ -0,0 +1,24 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you 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.
+ ~
+ ~
+ -->
+<html>
+ <body>
+ <h2>SideEffect API.</h2>
+ </body>
+</html>
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/Application.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/Application.java b/core/api/src/main/java/org/apache/polygene/api/structure/Application.java
new file mode 100644
index 0000000..609a9c8
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/Application.java
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import java.util.stream.Stream;
+import org.apache.polygene.api.activation.Activation;
+import org.apache.polygene.api.activation.ActivationEventListenerRegistration;
+
+/**
+ * The Application represents a whole Polygene application.
+ */
+public interface Application
+ extends ActivationEventListenerRegistration, Activation, MetaInfoHolder
+{
+ /**
+ * Application modes.
+ */
+ public enum Mode
+ {
+ /**
+ * Should be used for unit test runs. Created files etc. should be cleaned up between runs.
+ */
+ test,
+ /**
+ * Should be used during development. Typically create in-memory databases etc.
+ */
+ development,
+ /**
+ * Should be used in QA environments, and other production-like settings where different set of external
+ * resources are utilized.
+ */
+ staging,
+ /**
+ * Should be used in production. All databases are persistent on disk etc.
+ */
+ production
+ }
+
+ /**
+ * @return Application name
+ */
+ String name();
+
+ /**
+ * The version of the application. This can be in any format, but
+ * most likely will follow the Dewey format, i.e. x.y.z.
+ *
+ * @return the version of the application
+ */
+ String version();
+
+ /**
+ * @return Application Mode
+ */
+ Mode mode();
+
+ /**
+ * Find a Layer.
+ *
+ * @param layerName Layer name
+ * @return Found Layer, never returns null
+ * @throws IllegalArgumentException if there's no such Layer
+ */
+ Layer findLayer( String layerName )
+ throws IllegalArgumentException;
+
+ /**
+ * Find a Module.
+ *
+ * @param layerName Layer name
+ * @param moduleName Module name
+ * @return Found Module, never returns null
+ * @throws IllegalArgumentException if there's no such Module
+ */
+ Module findModule( String layerName, String moduleName )
+ throws IllegalArgumentException;
+
+ /**
+ * @return Application Descriptor
+ */
+ ApplicationDescriptor descriptor();
+
+ Stream<? extends Layer> layers();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/ApplicationDescriptor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/ApplicationDescriptor.java b/core/api/src/main/java/org/apache/polygene/api/structure/ApplicationDescriptor.java
new file mode 100644
index 0000000..82d01e0
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/ApplicationDescriptor.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import org.apache.polygene.api.PolygeneAPI;
+import org.apache.polygene.api.util.VisitableHierarchy;
+
+/**
+ * Application Descriptor.
+ */
+public interface ApplicationDescriptor
+ extends VisitableHierarchy<Object, Object>
+{
+ /**
+ * Create a new instance of the Application.
+ * @param runtime Polygene Runtime
+ * @param importedServiceInstances Imported Services instances
+ * @return a new instance of the Application.
+ */
+ Application newInstance( PolygeneAPI runtime, Object... importedServiceInstances );
+
+ /**
+ * @return the Application's name
+ */
+ String name();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/Layer.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/Layer.java b/core/api/src/main/java/org/apache/polygene/api/structure/Layer.java
new file mode 100644
index 0000000..2271047
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/Layer.java
@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import java.util.stream.Stream;
+import org.apache.polygene.api.activation.Activation;
+import org.apache.polygene.api.activation.ActivationEventListenerRegistration;
+
+/**
+ * The Layer represents a single layer in a Polygene application.
+ */
+public interface Layer
+ extends ActivationEventListenerRegistration, Activation, MetaInfoHolder
+{
+ /**
+ * @return the Layer's name
+ */
+ String name();
+
+ Application application();
+
+ Stream<? extends Module> modules();
+
+ LayerDescriptor descriptor();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/LayerDescriptor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/LayerDescriptor.java b/core/api/src/main/java/org/apache/polygene/api/structure/LayerDescriptor.java
new file mode 100644
index 0000000..e8270ae
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/LayerDescriptor.java
@@ -0,0 +1,57 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import java.util.stream.Stream;
+import org.apache.polygene.api.common.Visibility;
+import org.apache.polygene.api.composite.ModelDescriptor;
+import org.apache.polygene.api.composite.TransientDescriptor;
+import org.apache.polygene.api.entity.EntityDescriptor;
+import org.apache.polygene.api.object.ObjectDescriptor;
+import org.apache.polygene.api.value.ValueDescriptor;
+
+/**
+ * Layer Descriptor.
+ */
+public interface LayerDescriptor
+{
+
+ /**
+ * @return the Layer's name
+ */
+ String name();
+
+ Layer instance();
+
+ /**
+ * @return Layers used by this Layer
+ */
+ UsedLayersDescriptor usedLayers();
+
+ Stream<? extends ObjectDescriptor> visibleObjects( Visibility visibility );
+
+ Stream<? extends TransientDescriptor> visibleTransients( Visibility visibility );
+
+ Stream<? extends EntityDescriptor> visibleEntities( Visibility visibility );
+
+ Stream<? extends ValueDescriptor> visibleValues( Visibility visibility );
+
+ Stream<? extends ModelDescriptor> visibleServices( Visibility visibility );
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/MetaInfoHolder.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/MetaInfoHolder.java b/core/api/src/main/java/org/apache/polygene/api/structure/MetaInfoHolder.java
new file mode 100644
index 0000000..eea762e
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/MetaInfoHolder.java
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+/**
+ * MetaInfo holder.
+ */
+public interface MetaInfoHolder
+{
+
+ /**
+ * Get metadata that implements the given type.
+ * The info is registered during assembly of the application.
+ *
+ * @param infoType the type of metadata to be returned
+ *
+ * @return the metadata for the given type, or <code>null</code> if
+ * no such metadata has been registered
+ */
+ <T> T metaInfo( Class<T> infoType );
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/Module.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/Module.java b/core/api/src/main/java/org/apache/polygene/api/structure/Module.java
new file mode 100644
index 0000000..635615f
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/Module.java
@@ -0,0 +1,94 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import org.apache.polygene.api.activation.ActivationEventListenerRegistration;
+import org.apache.polygene.api.composite.TransientBuilderFactory;
+import org.apache.polygene.api.injection.scope.Structure;
+import org.apache.polygene.api.object.ObjectFactory;
+import org.apache.polygene.api.query.QueryBuilderFactory;
+import org.apache.polygene.api.service.ServiceFinder;
+import org.apache.polygene.api.unitofwork.UnitOfWorkFactory;
+import org.apache.polygene.api.value.ValueBuilderFactory;
+
+/**
+ * API for interacting with a Module. Instances
+ * of this can be accessed by using the {@link Structure}
+ * injection scope.
+ */
+public interface Module
+ extends ActivationEventListenerRegistration,
+ MetaInfoHolder,
+ ObjectFactory,
+ TransientBuilderFactory,
+ ValueBuilderFactory,
+ QueryBuilderFactory,
+ ServiceFinder
+{
+
+ /**
+ * @return the Module's name
+ */
+ String name();
+
+ ModuleDescriptor descriptor();
+
+ /**
+ * @return the Layer that the Module is declared in.
+ */
+ LayerDescriptor layer();
+
+ /** Returns the TypeLookup for the Module.
+ * TypeLookup handles all the types visible from within this Module.
+ *
+ * @return TypeLookup for this Module
+ */
+ TypeLookup typeLookup();
+
+ /** Returns the UnitOfWorkFactory for this Module.
+ *
+ * @return the UnitOfWorkFactory of this Module.
+ */
+ UnitOfWorkFactory unitOfWorkFactory();
+
+ /** Returns the ServiceFinder for this Module.
+ *
+ * @return the ServiceFinder for this Module.
+ */
+ ServiceFinder serviceFinder();
+
+ /** Returns the ValueBuilderFactory for this Module.
+ *
+ * @return the ValueBuilderFactory for this Module.
+ */
+ ValueBuilderFactory valueBuilderFactory();
+
+ /** Returns the TransientBuilderFactory for this Module.
+ *
+ * @return the TransientBuilderFactory for this Module.
+ */
+ TransientBuilderFactory transientBuilderFactory();
+
+ /** Returns the ObjectFactory for this Module.
+ *
+ * @return the ObjectFactory for this Module.
+ */
+ ObjectFactory objectFactory();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/ModuleDescriptor.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/ModuleDescriptor.java b/core/api/src/main/java/org/apache/polygene/api/structure/ModuleDescriptor.java
new file mode 100644
index 0000000..006ab06
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/ModuleDescriptor.java
@@ -0,0 +1,96 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import java.util.stream.Stream;
+import org.apache.polygene.api.composite.TransientDescriptor;
+import org.apache.polygene.api.entity.EntityDescriptor;
+import org.apache.polygene.api.object.ObjectDescriptor;
+import org.apache.polygene.api.service.ImportedServiceDescriptor;
+import org.apache.polygene.api.service.ServiceDescriptor;
+import org.apache.polygene.api.value.ValueDescriptor;
+
+/**
+ * Module Descriptor.
+ */
+public interface ModuleDescriptor
+{
+ String name();
+
+ LayerDescriptor layer();
+
+ /**
+ * @return the Module's ClassLoader
+ */
+ ClassLoader classLoader();
+
+ /**
+ * @param typeName name of a transient composite type
+ *
+ * @return the descriptor for a transient composite or null if the class could not be found or the transient composite is not visible
+ */
+ TransientDescriptor transientDescriptor( String typeName );
+
+ /**
+ * @param typeName name of an entity composite type
+ *
+ * @return the descriptor for an entity composite or null if the class could not be found or the entity composite is not visible
+ */
+ EntityDescriptor entityDescriptor( String typeName );
+
+ /**
+ * @param typeName name of an object type
+ *
+ * @return the descriptor for an object or null if the class could not be found or the object is not visible
+ */
+ ObjectDescriptor objectDescriptor( String typeName );
+
+ /**
+ * @param typeName name of a value composite type
+ *
+ * @return the descriptor for a value composite or null if the class could not be found or the value composite is not visible
+ */
+ ValueDescriptor valueDescriptor( String typeName );
+
+ Stream<? extends TransientDescriptor> findVisibleTransientTypes();
+
+ Stream<? extends ValueDescriptor> findVisibleValueTypes();
+
+ Stream<? extends EntityDescriptor> findVisibleEntityTypes();
+
+ Stream<? extends ObjectDescriptor> findVisibleObjectTypes();
+
+ Stream<? extends TransientDescriptor> transientComposites();
+
+ Stream<? extends ValueDescriptor> valueComposites();
+
+ Stream<? extends EntityDescriptor> entityComposites();
+
+ Stream<? extends ObjectDescriptor> objects();
+
+ Stream<? extends ImportedServiceDescriptor> importedServices();
+
+ Stream<? extends ServiceDescriptor> serviceComposites();
+
+ Module instance();
+
+ TypeLookup typeLookup();
+}
http://git-wip-us.apache.org/repos/asf/zest-java/blob/1c722f44/core/api/src/main/java/org/apache/polygene/api/structure/TypeLookup.java
----------------------------------------------------------------------
diff --git a/core/api/src/main/java/org/apache/polygene/api/structure/TypeLookup.java b/core/api/src/main/java/org/apache/polygene/api/structure/TypeLookup.java
new file mode 100644
index 0000000..ceafc20
--- /dev/null
+++ b/core/api/src/main/java/org/apache/polygene/api/structure/TypeLookup.java
@@ -0,0 +1,195 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.apache.polygene.api.structure;
+
+import java.lang.reflect.Type;
+import java.util.List;
+import java.util.stream.Stream;
+import org.apache.polygene.api.composite.AmbiguousTypeException;
+import org.apache.polygene.api.composite.ModelDescriptor;
+import org.apache.polygene.api.composite.TransientDescriptor;
+import org.apache.polygene.api.entity.EntityDescriptor;
+import org.apache.polygene.api.object.ObjectDescriptor;
+import org.apache.polygene.api.value.ValueDescriptor;
+
+public interface TypeLookup
+{
+ /**
+ * Lookup first Object Model matching the given Type.
+ *
+ * <p>First, if Object Models exactly match the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>exact</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Second, if Object Models match a type assignable to the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>assignable</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return First matching Object Model
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ ObjectDescriptor lookupObjectModel( Class<?> type ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup first Transient Model matching the given Type.
+ *
+ * <p>First, if Transient Models exactly match the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>exact</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Second, if Transient Models match a type assignable to the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>assignable</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return First matching Transient Model
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ TransientDescriptor lookupTransientModel( Class<?> type ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup first Value Model matching the given Type.
+ *
+ * <p>First, if Value Models exactly match the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>exact</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Second, if Value Models match a type assignable to the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>assignable</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return First matching Value Model
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ ValueDescriptor lookupValueModel( Class<?> type ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup first Entity Model matching the given Type.
+ *
+ * <p>First, if Entity Models exactly match the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>exact</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Second, if Entity Models match a type assignable to the given type, the closest one (Visibility then Assembly order) is returned.
+ * Multiple <b>assignable</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * <p><b>Should be used for creational use cases only.</b> For non-creational use cases see
+ * {@link #lookupEntityModels(Class)}.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return First matching Entity Model
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ EntityDescriptor lookupEntityModel( Class<?> type ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup all Entity Models matching the given Type.
+ *
+ * <p>Returned List contains, in order, Entity Models that: </p>
+ *
+ * <ul>
+ * <li>exactly match the given type, in Visibility then Assembly order ;</li>
+ * <li>match a type assignable to the given type, in Visibility then Assembly order.</li>
+ * </ul>
+ *
+ * <p>Multiple <b>exact</b> matches with the same Visibility are <b>forbidden</b> and result in an AmbiguousTypeException.</p>
+ * <p>Multiple <b>assignable</b> matches are <b>allowed</b> to enable polymorphic fetches and queries.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * <p><b>Should be used for non-creational use cases only.</b> For creational use cases see
+ * {@link #lookupEntityModel(Class)}.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return All matching Entity Models
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ List<EntityDescriptor> lookupEntityModels( Class<?> type ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup first ServiceDescriptor/ImportedServiceDescriptor matching the given Type.
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * <p>See {@link #lookupServiceModels(Type)}.</p>
+ *
+ * @param serviceType Looked up Type
+ *
+ * @return First matching Service
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ ModelDescriptor lookupServiceModel( Type serviceType ) throws AmbiguousTypeException;
+
+ /**
+ * Lookup all ServiceDescriptors matching the given Type.
+ *
+ * <p>Returned List contains, in order, ServiceReferences that: </p>
+ *
+ * <ul>
+ * <li>exactly match the given type, in Visibility then Assembly order ;</li>
+ * <li>match a type assignable to the given type, in Visibility then Assembly order.</li>
+ * </ul>
+ *
+ * <p>Multiple <b>exact</b> matches with the same Visibility are <b>allowed</b> to enable polymorphic lookup/injection.</p>
+ * <p>Multiple <b>assignable</b> matches with the same Visibility are <b>allowed</b> for the very same reason.</p>
+ *
+ * <p>Type lookup is done lazily and cached.</p>
+ *
+ * @param type Looked up Type
+ *
+ * @return All matching ServiceReferences
+ * @throws AmbiguousTypeException when a type ambiguity is found
+ */
+ List<? extends ModelDescriptor> lookupServiceModels( Type type ) throws AmbiguousTypeException;
+
+ /**
+ * @return All visible Objects, in visibility order
+ */
+ Stream<ObjectDescriptor> allObjects();
+
+ /**
+ * @return All visible Transients, in visibility order
+ */
+ Stream<TransientDescriptor> allTransients();
+
+ /**
+ * @return All visible Values, in visibility order
+ */
+ Stream<ValueDescriptor> allValues();
+
+ /**
+ * @return All visible Entities, in visibility order
+ */
+ Stream<EntityDescriptor> allEntities();
+
+ /**
+ * @return All visible Services, in visibility order
+ */
+ Stream<? extends ModelDescriptor> allServices();
+}