This blog is mainly about Java...

Monday, April 6, 2009

All unique annotations we are using in our Java EE 5 (Seam 2.1.1 GA and EJB 3 / Hibernate 3) project

Here is all the unique annoations we are using in our project (Seam 2.1.1, Hibernate, JPA, EJB 3 annotations) with a short explanation on each of them.

@AroundInvoke -- To add an interceptor to a bean, you need to write a class with a method annotated @AroundInvoke and annotate the bean with an @Interceptors annotation that specifies the name of the interceptor class.
@Asynchronous -- Specifies that the method call is processed asynchronously.
@AutoCreate -- Specifies that a component will be automatically created, even if the client does not specify create=true.
@Basic(LAZY) -- Tells the entitymanager to lazily fetch the column. This is not needed since that is the default.
@Begin(flushMode = FlushModeType.MANUAL) -- Begins a long running conversation and sets flushmode to manual. Doesnt execute operation until flush() is called.
@Begin(join = true) -- Specifies that if a long-running conversation is already in progress, the conversation context is simply propagated.
@BypassInterceptors -- disable interceptors for the component. Features such as bijection, annotated security restrictions, synchronization and others are unavailable for components marked as @ByPassInterceptors.
@CaptchaResponse(message="#{messages['verificationError']}") -- Tells what kind of message the response of the captcha should be
@CollectionOfElements --hibernate annotation that is used in conjunction with Embeddables.
@Column(length=16777215, nullable=false) -- sets an entity column to 16kb in length and not null
@Column(unique = true) -- Sets this column to be unique
@Create -- Specifies that the method should be called when an instance of the component is instantiated by Seam. Note that create methods are only supported for JavaBeans and stateful session beans.
@DataModel -- Exposes an attribute of type java.util.List to the JSF page as an instance of javax.faces.model.DataModel. This allows us to use the list in a JSF <h:dataTable> with clickable links for each row.
@DataModelSelection -- Annotation that tells Seam to inject the List element that corresponded to the clicked button
@Deprecated -- Marks the method or class as deprecated
@Documented -- Used in conjuction with creating annotations. Will make the annotation available in JavaDoc
@Duration -- Specifies that a parameter of the asynchronous call is the duration before the call is processed (or first processed for recurring calls).
@Email -- Hibernate validator for emails
@Embeddable -- Marks a class as Embeddable
@Embedded -- Classes that are Embeddable will be Embedded in the other class that uses them. IE, Address is embeddable, and is @Embedded in Person
@End -- Specifies that a long-running conversation ends when this method returns a non-null outcome without exception.
@Entity -- Marks a class as an Entity
@Expiration -- Specifies that a parameter of the asynchronous call is the datetime at which the call is processed (or first processed for recurring calls).
@Factory(value="officerAdminContact", scope=ScopeType.EVENT) -- Creates a factory with the name officerAdminContact with a scope of Event.
@Filter(name="orgFilter",condition = "organization_id = :orgid") -- Marks a class as hibernate filter with the name orgFilter, and sets the condition of the filter
@FilterDef(name="orgFilter", parameters = { @ParamDef(type="long", name="orgid")}) -- Hibernate annotation that defines a filter. The name defines which filter should be defined, and sets what kind of parameters the filter has.
@GeneratedValue -- Sets a id to be generated automatically
@Id -- Sets an attribute as Id for the entity
@In(create = true) -- Injects the field and if it is null, it will create the field
@In(required = false) -- Injects the field and tells seam that this field can be null, and will not be created if it is null
@In(required=false, scope=ScopeType.APPLICATION) -- Injects a field and sets the scope to be Application wide
@In(scope = ScopeType.BUSINESS_PROCESS) -- Injects a field and sets the scope to be BUSINESS_PROCESS
@In(value = "#{s:hasRole('sysadmin')}") -- Injects a field with an EL expression that returns true or false. In this example true if the user has role of sysadmin.
@In(value = "org.jboss.seam.bpm.jbpm") -- Injects a seam component that bootstraps a JBPM SessionFactory
@Inherited -- Indicates that an annotation type is automatically inherited. Used in conjunction with creating annotations.(?)
@Install(precedence = Install.APPLICATION) -- The @Install annotation lets you control conditional installation of components that are required in some deployment scenarios and not in others. This is useful if: *You want to mock out some infrastructural component in tests. *You want change the implementation of a component in certain deployment scenarios. *You want to install some components only if their dependencies are available (useful for framework authors). APPLICATION is the default precedence. This is appropriate for most application components.
@JoinTable(name = "ProcessUserRoles", joinColumns = @JoinColumn(name = "userId"), inverseJoinColumns = @JoinColumn(name = "roleId")) - Tells which table and what column should be joined in a table.
@Lob -- Persistence annotation that specifies that the attribute should be a large object.
@Local(ArchivingConnector.class) -- Tells the ejb which interface is the Local. An EJB can use local client view only if it is really guaranteed that other enterprise beans or clients will only address the bean within a single JVM. If this is the case, such access will be carried out with direct method calls, instead of RMI.
@Logger -- Seam's Log4J.
@ManyToOne(fetch = FetchType.LAZY, optional = true) -- Defines which filed is ManyToOne relation, with default fetch size as LAZY and that the field is optional (can be null)
@Name("lostPasswordAction") -- Creates a seam component with the name "lostPasswordAction"
@NamedQuery(name = "applicationprocess.find", query = "select ap from ApplicationProcess ap join ap.organization o where = :processName and = :orgName") -- Creates a named query with the name "applicationprocess.find" which will execute the specified query. This means that you can call the query like this: entityManager.createNamedQuery("applicationprocess.find").getResultList();
@Namespace(value="") -- Specifies the configuration namespace of a Java package containing Seam components.
@NotEmpty -- NotEmpty checks for not null and empty
@Observer("") -- An observer listens to the following event. In this example it will listen to successfully logins
@Officer -- Custom annotation that defines a class or a method as restricted with the role of Officer
@OneToOne(cascade = CascadeType.ALL) -- One to one relation with all cascading
@Orgadmin -- Custom annotation that defines a class or a method as restricted with the role of Orgadmin
@Out(required = false) -- Outjects the variable in the seam scope event and tell that the object can be null. Similar as request.setAttribute("bestRestaurant", restaurant);
@Out(scope = ScopeType.EVENT, required = false) -- Same as above, because the default scope in Seam is EVENT.
@Out(scope=ScopeType.SESSION, required=false) -- Same as above only the scope is set to SESSION
@Override -- Marks a method as Override. This tells the compiler that this method should override a parent method inherited.
@Parent -- A hibernate annotation that reference the property as a pointer back to the owner (generally the owning entity)
@Pattern(regex="\\D*-\\D+") -- Hibernate validator that checks the value with a regex pattern
@PermissionCheck("upgrade") -- Override the default permission action name (which is the lower case version of the annotation name) with another value. Used in conjuction with custom annotations.
@PostConstruct -- javax.annotation.PostConstruct. Used on a method that needs to be executed after dependency injection is done to perform any initialization. Only one method can be annotated with this annotation. The method MUST NOT have any parameters except in the case of EJB interceptors in which case it takes an InvocationC ontext object as defined by the EJB specification. The return type of the method MUST be void. The method MUST NOT throw a checked exception. The method on which PostConstruct is applied MAY be public, protected, package private or private. The method MUST NOT be static except for the application client. If the method throws an unchecked exception the class MUST NOT be put into service except in the case of EJBs where the EJB can handle exceptions and even recover from them.
@PrePersist -- JPA annotation that will be called right before a persist is done. Similar annotations are: PostPersist, PreUpdate, PostUpdate, PreRemove, PostRemove and PostLoad.
@RaiseEvent("templateHandler.pdf") - If a method is annotated with @RaiseEvent, it will raise an event with the name "templateHandler.pdf" after the method is finished.
@RequestParameter -- Specifies that a component attribute is to be injected with the value of a request parameter. Basic type conversions are performed automatically.
@Restrict("#{s:hasRole('orgadmin') or s:hasRole('sysadmin')}") -- Tells seam that the class can only be used if the role is orgadmin or sysadmin
@Retention(RUNTIME) -- Indicates how long annotations with the annotated type are to be retained. If no Retention annotation is present on an annotation type declaration, the retention policy defaults to RetentionPolicy.CLASS.
@Role(name="asyncReminderAction", scope=ScopeType.EVENT) -- Allows a Seam component to be bound to multiple contexts variables. The @Name/@Scope annotations define a "default role". Each @Role annotation defines an additional role. * Name — the context variable name. * scope — the context variable scope. When no scope is explicitly specified, the default depends upon the component type.
@RoleCheck -- Meta-annotation that designates an annotation as being a role, requiring a security check prior to invoking the annotated method or class.
@RoleName -- Flags an entity field or method as representing the name of a role
@Scope(ScopeType.CONVERSATION) -- Sets the scope to be CONVERSATION
@Scope(ScopeType.EVENT) -- Sets the scope to be EVENT (default)
@Scope(ScopeType.SESSION) -- Sets the scope to be SESSION
@Startup -- Specifies that an instance of this component is created at system initialization time for an application scoped component, or when a session is started for a session scoped component. May only be applied to APPLICATION or SESSION scoped components.
@Stateless -- Component-defining annotation for a stateless session bean.
@SuppressWarnings("unchecked") -- Tells the compiler to suppress warnings of type unchecked. Normally from entityManager.createQuery().getResultList()
@Sysadmin -- Custom annotation that defines a class or a method as restricted with the role of Sysadmin
@Target({TYPE, METHOD}) -- Indicates the kinds of program element to which an annotation type is applicable.
@Temporal(TemporalType.TIMESTAMP) --JPA annotation for date attributes. This will set the timestamp on a variable automatically
@Test(dependsOnMethods = "setup") -- TestNG annotation that defines this test to be dependant on a test called setup, and cant be run until that test is finished.
@Transactional -- Specifies that a JavaBean component should have a similar transactional behavior to the default behavior of a session bean component. ie. method invocations should take place in a transaction, and if no transaction exists when the method is called, a transaction will be started just for that method.
@Transient -- Defines this field to be transient. It will not be stored or serialized.
@UniqueConstraint(columnNames = "{name,organization}") -- JPA annotation that in this case defines that the attributes name and organization together should be unique.
@UserFirstName -- Flags an entity field or method as representing the first name of a user
@UserLastName -- Flags an entity field or method as representing the last name of a user
@UserPassword(hash = "md5") --Flags an entity field or method as representing the password for a user. The hash method that is used is md5 here. However sha is more secure, and "none" is also a valid option, which will not hash anything.
@UserPrincipal --Flags an entity field or method as representing the principal (username) for a user
@UserRoles --Flags an entity field or method as representing the list of role memberships for a user
@Valid -- Hibernate validator that enables recursive validation of an associated object. If used on an field, it will check all the fields validators, ie @Valid Address address = new Address(); will check all the validators of class Adress.
@Validator --Allows a Seam component to act as a JSF validator. The annotated class must be a Seam component, and must implement javax.faces.validator.Validator.
@Version --JPA annotation that specifies the version field or property of an entity class that serves as its optimistic lock value. The version is used to ensure integrity when performing the merge operation and for optimistic concurrency control. Only a single Version property or field should be used per class; applications that use more than one Version property or field will not be portable. The Version property should be mapped to the primary table for the entity class; applications that map the Version property to a table other than the primary table will not be portable.
@WebParam(name="data") --Used with WebServices and is used to customize the mapping of a single parameter to a message part or element.
@WebService -- The purpose of this annotation is to mark an endpoint implementation as implementing a web service or to mark that a service endpoint interface as defining a web service interface. All endpoint implementation classes MUST have a WebService annotation and must meet the requirements of section 3.3 of the JAX-WS 2.0 specification.
@XmlRootElement --Maps a class or an enum type to an XML element. When a top level class or an enum type is annotated with the @XmlRootElement annotation, then its value is represented as XML element in an XML document.
//Example: Code fragment
class Point {
int x;
int y;
Point(int _x,int _y) {x=_x;y=_y;}

//Example: Code fragment corresponding to XML output
marshal( new Point(3,5), System.out);

<!-- Example: XML output -->

@XmlSeeAlso -- Instructs JAXB to also bind other classes when binding this class.
Java makes it impractical/impossible to list all sub-classes of a given class. This often gets in a way of JAXB users, as it JAXB cannot automatically list up the classes that need to be known to JAXBContext.
For example, with the following class definitions:

class Animal {}
class Dog extends Animal {}
class Cat extends Animal {}

The user would be required to create JAXBContext as JAXBContext.newInstance(Dog.class,Cat.class) (Animal will be automatically picked up since Dog and Cat refers to it.)
XmlSeeAlso annotation would allow you to write:
class Animal {}
class Dog extends Animal {}
class Cat extends Animal {}

This would allow you to do JAXBContext.newInstance(Animal.class). By the help of this annotation, JAXB implementations will be able to correctly bind Dog and Cat.

No comments: