Package org.eclipse.scout.rt.ui.html.json

Class JsonResponse

java.lang.Object
org.eclipse.scout.rt.ui.html.json.JsonResponse
public class JsonResponse extends Object

  • Field Details

  • Constructor Details

    • JsonResponse

      public JsonResponse()

    • JsonResponse

      public JsonResponse(Long sequenceNo)

  • Method Details

    • getSequenceNo

      public Long getSequenceNo()

    • addAdapter

      public void addAdapter(IJsonAdapter<?> adapter)
      Adds an adapter to the response. All adapters stored on the response are transferred to the client (browser) as JSON object. Only new adapters must be transferred, adapters already transferred to the client can be solely referenced by their ID.

      Note that in javascript the adapters are not created unless the first event is received.

    • addPropertyChangeEvent

      public JsonEvent addPropertyChangeEvent(String id, String propertyName, Object newValue)
      Parameters:
      id - Adapter ID
      propertyName - property name
      newValue - property value

    • addActionEvent

      public JsonEvent addActionEvent(String eventTarget, String eventType)

    • addActionEvent

      public JsonEvent addActionEvent(String eventTarget, String eventType, JSONObject eventData)
      Note: when converting the response to JSON, events on adapters that are also part of this response are ignored, see also doAddEvent(JsonEvent)

    • addActionEvent

      public JsonEvent addActionEvent(String eventTarget, String eventType, String eventReference, JSONObject eventData)
      Same as addActionEvent(String, String, JSONObject) but with an 'eventReference' added to the JSON event. This reference is considered additionally to 'eventTarget' when removing events (see removeJsonAdapter(String)).

      Note: when converting the response to JSON, events on adapters that are also part of this response are ignored, see also doAddEvent(JsonEvent)

    • replaceActionEvent

      public JsonEvent replaceActionEvent(String eventTarget, String eventType, JSONObject eventData)
      Note: when converting the response to JSON, events on adapters that are also part of this response are ignored, see also doAddEvent(JsonEvent)

    • containsAdapter

      public boolean containsAdapter(IJsonAdapter<?> adapter)

    • containsPropertyChangeEvent

      public boolean containsPropertyChangeEvent(String id, String propertyName)

    • registerBufferedEventsAdapter

      public void registerBufferedEventsAdapter(IJsonAdapter<?> adapter)
      Registers the given adapter as a holder of buffered events. Before executing toJson() those buffers are consumed automatically. (Additionally, all registered buffers can be consumed manually with fireProcessBufferedEvents().)

    • unregisterBufferedEventsAdapter

      public void unregisterBufferedEventsAdapter(IJsonAdapter<?> adapter)

    • markAsStartupResponse

      public void markAsStartupResponse()

    • isMarkedAsStartupResponse

      public boolean isMarkedAsStartupResponse()

    • getStartupData

      public JSONObject getStartupData()
      The (mutable) startupData object if the response is marked as "startup response", null otherwise.

    • markAsError

      public void markAsError(int errorCode, String errorMessage)
      Marks this JSON response as "error" (default is "success").
      Parameters:
      errorCode - An arbitrary number indicating the type of error.
      errorMessage - A message describing the error. This message is mostly useful for debugging purposes. Usually, it is not shown to the user, because it is not language-dependent. If possible, the displayed message is translated by the client using the errorCode parameter (see Session.js).

    • isMarkedAsError

      public boolean isMarkedAsError()

    • isWritable

      public boolean isWritable()
      Returns:
      true if this response is still writable (e.g. new adapters and events can be added). After toJson() was called and the resulting JSON was sent to the UI, this method will return false forever.

    • assertWritable

      protected void assertWritable()

    • toJson

      public JSONObject toJson()
      Returns a JSON string representation of this instance. This method is typically called at the end of a request.

      Attention: This method is not free of side effects!

      • Buffered events are processed. This may lead to the addition of new adapters and events (see implementations of IJsonAdapter.processBufferedEvents()).
      • After that, the request will not be writable anymore! Any attempt to alter the response afterwards results in an Assertions.AssertionException to be thrown. isWritable() will always returns false.
      The return value of this method is returned as a valid JSON object to the client-side GUI. All new adapters (= adapters not yet transferred to the UI), are put as a list in the "adapterData" property. All events are transferred in the "events" property. An ascending sequence number is put in the "#" property.

      This method will call the toJson() method on all adapter objects. Note that you can NOT create new adapter instances when the toJson() method runs! All new adapter instances must be created before: either in the attachModel() method or in an event handler method like handleXYZ(). The technical reason for this is, first: new adapters are added to the current response (see UiSession), but at the point in time toJson() is called, we already have a new instance of the current response. Second: when we loop through the adapterMap and call toJson() for each adapter, if the adapter would create another adapter in its toJson() method, the adapterMap would grow, which would cause a ConcurrentModificationException. Additionally we should conceptually separate object creation from JSON output creation.

    • toJsonInternal

      protected JSONObject toJsonInternal()

    • fireProcessBufferedEvents

      public void fireProcessBufferedEvents()
      Causes all registered IJsonAdapters to process their buffered events. This may add some events and adapters to this response. This method is called automatically during toJson().

    • doAddEvent

      protected boolean doAddEvent(JsonEvent event)
      When we send a new adapter in the JSON response we have to ignore all events for that adapter, since the adapter data already describes the latest state of the adapter.

      For property change events this is just an optimization to reduce the response size.
      For other event types it may be crucial that the events are not sent.
      Example: NodesInserted event on tree must not be sent since the same nodes are already sent by Tree.toJson.

    • removeJsonAdapter

      public void removeJsonAdapter(String id)
      Removes all traces of the adapter with the given ID from the current response. This includes all events with the given ID as target or "reference". Also, if the adapter was registered as "buffered events adapter", it is unregistered automatically. Any deferred model event for this adapter will therefore not be handled.
      Parameters:
      id - Adapter ID to be removed

    • getEventList

      public List<JsonEvent> getEventList()
      Returns:
      a copy of the event list

    • eventList

      protected List<JsonEvent> eventList()

    • adapterMap

      protected Map<String,IJsonAdapter<?>> adapterMap()

    • startupData

      protected JSONObject startupData()

    • error

      protected boolean error()

    • errorCode

      protected int errorCode()

    • errorMessage

      protected String errorMessage()

    • isEmpty

      public boolean isEmpty()

    • toString

      public String toString()
      Overrides:
      toString in class Object