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(); +}
