001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: * $Header:$
018: */
019: package org.apache.beehive.controls.system.ejb;
020:
021: import java.lang.annotation.ElementType;
022: import java.lang.annotation.Retention;
023: import java.lang.annotation.RetentionPolicy;
024: import java.lang.annotation.Target;
025:
026: import org.apache.beehive.controls.api.bean.AnnotationMemberTypes;
027: import org.apache.beehive.controls.api.bean.ControlInterface;
028: import org.apache.beehive.controls.api.bean.AnnotationConstraints.MembershipRule;
029: import org.apache.beehive.controls.api.bean.AnnotationConstraints.MembershipRuleValues;
030: import org.apache.beehive.controls.api.properties.PropertySet;
031:
032: /**
033: * Enterprise Java Bean Control base interface
034: */
035: @ControlInterface(defaultBinding="org.apache.beehive.controls.system.ejb.EJBControlImpl")
036: public interface EJBControl {
037: /**
038: * EJBHome specifies the target EJB's home interface for the EJB control using the following attributes:
039: * <ul>
040: * <li><b>jndiName</b> specifies the JNDI name of the target EJB's home interface
041: * (e.g. EJBNameHome). This value may also be an URL using the "JNDI:"
042: * protocol (e.g. jndi://username:password@host:port/EJBNameHome).
043: * </li>
044: * <li><b>ejbLink</b> specifies the name of the target EJB using the application
045: * relative path to the EJB JAR. This syntax causes the runtime to
046: * use an application scoped name when locating the referenced EJB.
047: * The naming syntax is jarfile.jar#ejb-name (e.g. ejbModule.jar#HelloBean).
048: * </li>
049: * </ul>
050: * An EJB Control in a web application would reference an EJB type using the
051: * fully qualified name of the control interface with the suffix "jcx". For example,
052: * a control of type <code>controls.HelloEjbControl</code> would resolve the EJB using
053: * the following entry in web.xml:
054: * <pre>
055: * <ejb-ref>
056: * <ejb-ref-name>controls.HelloEjbControl.jcx</ejb-ref-name>
057: * <ejb-ref-type>Session</ejb-ref-type>
058: * <home>ejbs.HelloBeanHome</home>
059: * <remote>ejbs.HelloBeanRemote</remote>
060: * <ejb-link>ejbModule.jar#HelloBean</ejb-link>
061: * </ejb-ref>
062: * </pre>
063: */
064: @PropertySet
065: @Retention(RetentionPolicy.RUNTIME)
066: @Target({ElementType.TYPE,ElementType.FIELD})
067: // allow override on declaration
068: @MembershipRule(MembershipRuleValues.EXACTLY_ONE)
069: public @interface EJBHome {
070: String jndiName() default "";
071:
072: String ejbLink() default "";
073: }
074:
075: /**
076: * JNDIContextEnv specifies the environment properties for the JNDI context that will
077: * be used to lookup the target EJB. This attribute is optional. If you are using
078: * an URL with the "JNDI:" protocol or if you want to use a JNDI context with the
079: * default envirnoment properties, you do not need a specify any values for this attribute.
080: */
081: @PropertySet
082: @Retention(RetentionPolicy.RUNTIME)
083: @Target({ElementType.TYPE,ElementType.FIELD})
084: // allow override on declaration
085: public @interface JNDIContextEnv {
086: @AnnotationMemberTypes.Optional
087: String contextFactory() default "";
088:
089: @AnnotationMemberTypes.Optional
090: String providerURL() default "";
091:
092: @AnnotationMemberTypes.Optional
093: String principal() default "";
094:
095: @AnnotationMemberTypes.Optional
096: String credentials() default "";
097: }
098:
099: /**
100: * Returns an instance of the home interface associated with
101: * the target bean component.
102: */
103: public Object getEJBHomeInstance();
104:
105: /**
106: * Returns true if the EJB control currently has a target bean instance
107: * upon which bean business interface methods may be invoked. This will
108: * be true after a successful create() or single select finder method
109: * execution, or in cases where implicit creation or find has occurred
110: * by the control on the control users behalf. This provides a simple
111: * way to procedurally check the status of explicit or implicit
112: * bean instance creation or find operations.
113: */
114: public boolean hasEJBBeanInstance();
115:
116: /**
117: * Returns the current target instance of the bean business interface
118: * used for business interface method invocations. This API is
119: * provided for advanced use cases were direct access to the local/
120: * remote interfaces outside of the control is required. It will
121: * return <code>null</code> if no target instance is currently
122: * selected.
123: */
124: public Object getEJBBeanInstance();
125:
126: /**
127: * Returns the last EJB exception serviced by the EJB control on the
128: * developers behalf. This can be used to discover or log additional
129: * information, for example when a create or find method is unable to
130: * locate a target bean instance.
131: */
132: public Throwable getEJBException();
133: }
|