net.sf.eBus.messages.FieldDisplayIndex Maven / Gradle / Ivy
//
// Copyright 2020 Charles W. Rapp
//
// Licensed 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 net.sf.eBus.messages;
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 field-level, run-time annotation is used to define field
* ordering for human presentation only. Field ordering
* for serialization purposes is determined by eBus based on
* field size. But this serialization ordering when displaying
* message fields to humans can be confusing. To reduce this
* confusion, message fields can be ordered by attaching this
* field display index to each field. The overall field display
* ordering is from {@link EMessageObject} down to the final
* message class, with the super class fields displayed first
* (based on the their own {@code @FieldDisplayIndex} ordering)
* and the final class fields displayed last.
*
* Note that field indexing should start at zero but this is not
* necessary. It is also recommended that field indices increment
* by one. But again this is not necessary. Fields will be
* ordered numerically. What should not occur is two fields in
* the same class having the same field display index. That will
* result in an indeterminate ordering. Of course fields from
* two different classes may, and probably will, share the same
* field display index.
*
*
* If this annotation is not used then field order is determined
* by {@code Class.getDeclaredFields()}. Field ordering will
* still be from top-most base class down to the bottom class.
*
* Example field display ordering
* public final class LatestEquityQuoteReply
extends EReplyMessage
implements Serializable
{
@FieldDisplayIndex(index = 0)
public final ParticipantType participantType;
@FieldDisplayIndex(index = 1)
public final String participant;
@FieldDisplayIndex(index = 2)
public final PriceType quoteType;
@FieldDisplayIndex(index = 3)
public final PriceSize bid;
@FieldDisplayIndex(index = 4)
public final PriceSize ask;
...
}
*
* {@link net.sf.eBus.messages.EReplyMessage} also has two
* ordered fields: {@code replyStatus} and {@code replyReason}.
* {@link net.sf.eBus.messages.type.MessageType#displayFields}
* returns fields in this order:
*
*
* - replyStatus
* - replyReason
* - participantType
* - participant
* - quoteType
* - bid
* - ask
*
*
* This annotation is needed since {@code @EFieldInfo} annotation
* was deprecated. That annotation defined both the field
* serialization order and display order. As noted above,
* field serialization order is now defined by eBus but this left
* display order undefined. {@code @FieldDisplayIndex} corrects
* this oversight.
*
*
* @author Charles W. Rapp
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
@Documented
public @interface FieldDisplayIndex
{
/**
* Returns the field display index.
* @return field display index.
*/
int index();
} // end of annotation FieldDisplayIndex