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

Class JsonResponse

  • public class JsonResponse
extends Object

    • Constructor Detail

      • JsonResponse

        public JsonResponse()

      • JsonResponse

        public JsonResponse​(Long sequenceNo)

    • Method Detail

      • 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

      • 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

      • startupData

        protected JSONObject startupData()

      • error

        protected boolean error()

      • errorCode

        protected int errorCode()

      • errorMessage

        protected String errorMessage()

      • isEmpty

        public boolean isEmpty()