SECDInterfaceThread.java

Go to the documentation of this file.

/*
 * Project: Server for annotations sharing
 * Author: Ing. Jaroslav Dytrych idytrych@fit.vutbr.cz
 * File: SECDInterfaceThread.java
 * Description: Class provides links anotation client with NLP for questions on vocabulary items.
 */

/**
 * @file SECDInterfaceThread.java
 *
 * @brief Class forwards queries from anotation client to the NLP server and and 
 * creates a message for annotation client with the results from the NLP server.
 */

package cz.vutbr.fit.knot.annotations.modules.SECDictionaryInterface;

import cz.vutbr.fit.knot.annotations.app.AppBean;
import cz.vutbr.fit.knot.annotations.app.Constants;
import cz.vutbr.fit.knot.annotations.comet.RequestInfo;
import cz.vutbr.fit.knot.annotations.comet.RequestInfo.EntityRequest;
import cz.vutbr.fit.knot.annotations.entity.ServerSetting;
import cz.vutbr.fit.knot.annotations.entity.UserGroup;
import cz.vutbr.fit.knot.annotations.entity.attribute.EntityAdditionalAttribute;
import cz.vutbr.fit.knot.annotations.entity.attribute.EntityAttribute;
import cz.vutbr.fit.knot.annotations.entity.attribute.EntityAttribute.Entity;
import cz.vutbr.fit.knot.annotations.modules.suggestionManager.SECAPIConn;
import cz.vutbr.fit.knot.annotations.modules.suggestionManager.SECAPIInterface;
import cz.vutbr.fit.knot.annotations.modules.suggestionManager.SecApiReqTypeDef;
import cz.vutbr.fit.knot.annotations.modules.suggestionManager.SuggestionManager;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Iterator;
import java.util.List;
import java.util.Set;
import java.util.logging.Level;
import java.util.logging.Logger;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;
import org.json.simple.JSONValue;

/**
 * @brief Class forwards queries from anotation client to the SEC API server and and 
 * creates a message for annotation client with the results from the SEC API server.
 * 
 * @author Martin Petr (xpetrm05)
 */
public class SECDInterfaceThread extends Thread{
  /** Informations about client request */
  private RequestInfo requestInfo;
  /** Detailed informations about request for entities */
  private EntityRequest request;
  
  /** New prefix of freebase image URI */
  public static final String PREFIX_NEW = "https://www.googleapis.com/freebase/v1/image/";
  /** New postfix of freebase image URI */
  public static final String POSTFIX_NEW = "?maxwidth=500&maxheight=500";
  /** Old prefix of freebase image URI which must be replaced */
  public static final String PREFIX = "api.freebase.com/api/trans/raw/";
  
  /** Maximum results to return if limit is not specified by client */
  public static final int MAX_RESULTS = 50;
  
  /** 
   * Name of column in KB where name of entity is stored. 
   * Entities in KB have more options where name can be so fallback must be used 
   */
  public static final ArrayList<String> NAME_ATTRIBUTES = new ArrayList<String>(Arrays.asList(
    "name",
    "preferred_term",
    "display_term",
    "short_name",
    "alias"
  ));
  /** Name of column in KB where URI of entity is stored. */
  public static final String URI_ATTRIBUTE = "identifier";
  /** Name of column in KB where URI of image of entity is stored. */
  public static final String VIS_REPRESENTATION_ATTRIBUTE = "image";
  /** Alternative name of column in KB where URI of image of entity is stored. */
  public static final String ALT_VIS_REPRESENTATION_ATTRIBUTE = "freebase_image";
  /** Name of column in KB where description of entity is stored. */
  public static final String DESCRIPTION_ATTRIBUTE = "description";
  
  /** Separator of values in multivalue attributes */
  public static final String MULTIPLE_DATA_SEPARATOR = "\\|";
  
  /** Allowed postfix of image file name */
  private final static ArrayList<String> ALLOWED_POSTFIX = new ArrayList<String>(Arrays.asList(
    "jpg",
    "gif",
    "bmp",
    "png",
    "jpeg"
  ));
  
  /** Attributes which should be requested from SEC API */
  public static final ArrayList<String> REQUESTED_ATTRIBUTES = new ArrayList<String>(Arrays.asList(
    "name",
    "preferred_term",
    "display_term",
    "short_name",
    URI_ATTRIBUTE,
    VIS_REPRESENTATION_ATTRIBUTE,
    ALT_VIS_REPRESENTATION_ATTRIBUTE,
    DESCRIPTION_ATTRIBUTE
  ));
  
  /**
   * Constructor.
   * 
   * @param requestInfo object with informations about requests from client
   */
  public SECDInterfaceThread(RequestInfo requestInfo){
    super("SECDInterfaceThread");
    this.requestInfo = requestInfo;
    request = requestInfo.getEntityRequest();
  }
  
  /**
   * Method gets entities according to client's request and send the response 
   * to the client by comet channel.
   */
  @Override
  public void run() {
    String messageForClient = "";
    ArrayList<EntityAttribute> resultsArray = null;
    
    resultsArray = getResultFromSECAPI(request);
    
    // workaround for old URIs of Freebase images in KB
    if(resultsArray != null && !resultsArray.isEmpty() && Constants.VISUAL_REPRESENTATION_URI_CHANGE){
      Iterator<EntityAttribute> resultIt = resultsArray.iterator();
      while(resultIt.hasNext()){
        EntityAttribute currentAttr = resultIt.next();
        if(((Entity)currentAttr.getValue()).getVisualRepresentation()!= null){
          String uri = ((Entity)currentAttr.getValue()).getVisualRepresentation();
          if(!uri.isEmpty()){
            String[] result = uri.split(PREFIX);
            if(result.length == 2){
              String core = result[1];
              if(!core.isEmpty()){
                Entity currentValue = (Entity)currentAttr.getValue();
                currentValue.setVisualRepresentation(PREFIX_NEW + core + POSTFIX_NEW);
                currentAttr.setValue(currentValue);
              }
            }
          }
        }
      }
    }
    
    // make message with results for client
    if (resultsArray != null && !resultsArray.isEmpty()) {
      messageForClient = makeMessageFromResult(resultsArray);
    }
    
    if (messageForClient != null && !messageForClient.isEmpty()) {
      requestInfo.getSession().addMessageTS(messageForClient);
      requestInfo.getSession().notifyComet();
    }
  }  // run()
  
  /**
   * Method makes JSON string from EntityRequest object (that represents request 
   * for entity from client).
   * 
   * @param request request from client that will be parse
   * @return JSON string for SEC Store API
   */
  private String makeRequestString(EntityRequest request){
    StringBuilder resultBuilder = new StringBuilder();
    
    resultBuilder.append("{ \"getEntities\":\n");
    resultBuilder.append("{ \"type\":\n");
    resultBuilder.append("\"");
    resultBuilder.append(request.getType());
    resultBuilder.append("\",\n");
    resultBuilder.append(" \"filter\":\n");
    resultBuilder.append("\"");
    resultBuilder.append(request.getFilter());
    resultBuilder.append("\",\n");
    resultBuilder.append(" \"user\":\n");
    resultBuilder.append("\"");
    resultBuilder.append(requestInfo.getSession().getUser().getLogin());
    resultBuilder.append("\",\n");
    
    resultBuilder.append("\"userGroups\":[\n");
    Iterator<UserGroup> groupIt = requestInfo.getSession().getUser().getGroups().iterator();
    while(groupIt.hasNext()){
      UserGroup actualGroup = groupIt.next();
      resultBuilder.append("{\"uri\":");
      resultBuilder.append("\"");
      resultBuilder.append(EscapeCharsToSend(actualGroup.getUri()));
      resultBuilder.append("\",\n");
      resultBuilder.append("\"name\":");
      resultBuilder.append("\"");
      resultBuilder.append(actualGroup.getName());
      if(groupIt.hasNext()){
        resultBuilder.append("\"},\n");
      }
      else{
        resultBuilder.append("\"}\n");
      }
    }
    resultBuilder.append("],\n");
    resultBuilder.append(" \"userFrom\":\n");
    resultBuilder.append("\"");
    if(requestInfo.getSession().getUser().getComeFrom() != null){
      resultBuilder.append(requestInfo.getSession().getUser().getComeFrom());
    }else{
      resultBuilder.append("");
    }
    resultBuilder.append("\"}}\n");
    
    
    return resultBuilder.toString();
  } // makeRequestString()
  
  /** 
   * Method make string from array of EntityAtributes that will be sent to client.
   * 
   * @param responses array list with objects from SEC Store API
   * @return XML string for client
   */
  private String makeMessageFromResult(ArrayList<EntityAttribute> responses){
    StringBuilder resultString = new StringBuilder();
    Iterator<EntityAttribute> resultIt = responses.iterator();
    int counter = 0;
    Integer limit = request.getMaxResults();

    // If user didn't defined maximum results, default value is used
    if(limit == null || limit == -1){
      limit = MAX_RESULTS;
    }
    
    if (requestInfo.getSession().getProtocolLOD() < Constants.PROTOCOL_LOD_V2) {
      // Protocol v1.x is used
      resultString.append("<entities>");
      while(resultIt.hasNext()){
        EntityAttribute currentEntity = resultIt.next();
        if (currentEntity.getStringValue() == null || currentEntity.getStringValue().isEmpty()) {
          continue;  // client can not handle entity without name
        }
        if (currentEntity.getUri() == null || currentEntity.getUri().isEmpty()) {
          continue;  // client can not handle entity without URI
        }
        resultString.append(currentEntity.toXmlString());
      }
      resultString.append("</entities>");
    } else {  // Protocol v2
      //Building header of msg
      resultString.append("<entities name=\"").append(request.getFilter());
      
      if(request.getType() != null){
        resultString.append("\" type=\"").append(request.getType()).append("\">");
      }
      else{
        resultString.append("\">");
      }

      //Building list of entitites
      while(resultIt.hasNext()){
        EntityAttribute currentEntity = resultIt.next();
        counter++;

        if (currentEntity.getStringValue() == null || currentEntity.getStringValue().isEmpty()) {
          continue;  // client can not handle entity without name
        }
        if (currentEntity.getUri() == null || currentEntity.getUri().isEmpty()) {
          continue;  // client can not handle entity without URI
        }

        // Getting just exact requested number of entities
        if(counter <= limit){
          resultString.append(currentEntity.toXMLResponseStringV2());
        }
        else{
          break;
        }
      }

      resultString.append("</entities>");
    }  // Protocol v2

    return resultString.toString();
  }  // makeMessageFromResult()
  
  /**
   * Method parse response string from the SEC Store API and save entities in it to 
   * array.
   * 
   * @param JSONString JSON string from SEC Store API
   * @return list of EntityAtributes parsed from JSON String
   */
  private ArrayList<EntityAttribute> makeArrayFromResult(String JSONString){
    ArrayList<EntityAttribute> returnList = new ArrayList<EntityAttribute>();

    // create JSON array from received textual data
    JSONObject jsonResponse = (JSONObject)JSONValue.parse(JSONString);
    if (jsonResponse == null) {
      if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
        String msg = "Unable to parse received JSON string with vocabulary entities.";
        Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
      }
      return returnList;
    }
    
    // get all recived entities
    JSONArray jsonEntities = (JSONArray)jsonResponse.get("entities");
    if (jsonEntities == null) {
      if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
        String msg = "Unable to get new suggestions data from received JSON.";
        Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
      }
      return returnList;
    }
    else if (jsonEntities.isEmpty()) {
      return returnList;
    }
    
    //go trough all recived entities
    for(int index = 0; index < jsonEntities.size(); index++){
      // obtain one entity
      JSONObject currentEntity = (JSONObject)jsonEntities.get(index);
      
      String name;
      String uri;
      String visualUri;
      String description;
      String type;
      
      
      // parse uri from entity JSON string
      try {
         uri = (String)currentEntity.get("uri");    
      }
      catch (ClassCastException e) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "Entity uri is not a String type.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        continue;
      }
      
      // parse type from entity JSON string
      try {
         type = (String)currentEntity.get("type");    
      }
      catch (ClassCastException e) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "Entity type is not a String type.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        continue;
      }
      
      // parse name from entity JSON string
      try {
         name = (String)currentEntity.get("name");   
      }
      catch (ClassCastException e) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "Entity name is not a String type.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        continue;
      }
    
      // parse uri of visual representation from entity JSON string
      try {
         visualUri = (String)currentEntity.get("visual_representation");    
      }
      catch (ClassCastException e) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "Entity uri of visual representation is not a String type.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        continue;
      }
      
      // parse description of entity from entity JSON string
      try {
         description = (String)currentEntity.get("description");    
      }
      catch (ClassCastException e) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "Entity uri of visual representation is not a String type.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        continue;
      }

      EntityAttribute attr = new EntityAttribute(name,type,uri,visualUri,description);
      ArrayList<EntityAdditionalAttribute> addAttrs = getAdditionalAttributes(currentEntity, attr);
      attr.setEntityAdditionalAttributes(addAttrs);
      returnList.add(attr);
    
    }
    
    return returnList;
  }  // makeArrayFromResult()
  
  /**
   * Creates escaped version of the provided textual data. It is used when
   * text to be sent to the SEC Store server contains special characters like
   * quotes and backslash. Method expects SEC Store server to store strings
   * enclosed in double quote. That's why double quote character needs to be
   * escaped and single quote not.
   */
  private String EscapeCharsToSend(String source) {
    String result = source;
    // string can have null value if suggestions type is not requested
    if (result != null) {
      result = result.replace("\\", "\\\\");
      result = result.replace("\"", "\\\"");
      result = result.replace("\n", " ");
      result = result.replace("\t", " ");
    }
    return result;
  } // EscapeCharsToSend()
  
  /**
   * Method searches vocabulary entities by using a SEC API.
   * 
   * @param request Request from client that will be searched
   * @return Returns finded vocabulary entities
   */
  public ArrayList<EntityAttribute> getResultFromSECAPI(EntityRequest request){
    ArrayList<EntityAttribute> retList = new ArrayList<EntityAttribute>();
    
    String secApiResults = "";
    
    if (Constants.USE_REMOTE_SEC_API || SECAPIInterface.isSecCommandEmpty()) {
      secApiResults = makeRemoteSECAPIRequest(request);
    } else {
      secApiResults = makeSECAPIRequest(request);
    }
    
    
    try {
      JSONObject jsonData = (JSONObject) JSONValue.parse(secApiResults);
      if (jsonData == null) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "List with dictionary entities was not returned from SEC API.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        return retList;
      }
      
      JSONArray jsonEntities = (JSONArray) jsonData.get("data");
      
      if (checkException(jsonData)) {
        return retList;
      }
      
      if (jsonEntities == null) {
        if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
          String msg = "List with dictionary entities was not returned from SEC API.";
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
        }
        return retList;
      }
      
      int numOfEntities = jsonEntities.size();
      for (int i = 0; i < numOfEntities; i++) {  // for each entity
        try {
          JSONObject entity = (JSONObject) jsonEntities.get(i);
          Set keySet = entity.keySet();
          Iterator kIt = keySet.iterator();
          if (kIt.hasNext()) {
            String type = kIt.next().toString();
            JSONObject entityAttributes = (JSONObject) entity.get(type);
            Iterator<String> namesIt = NAME_ATTRIBUTES.iterator();
            String name = null;
            while ((name == null || name.isEmpty()) && namesIt.hasNext()) {
              name = (String) entityAttributes.get(namesIt.next());
            }
            String uri = (String) entityAttributes.get(URI_ATTRIBUTE);
            String visual_representation = (String) entityAttributes.get(VIS_REPRESENTATION_ATTRIBUTE);
            if (visual_representation == null) {
              visual_representation = (String) entityAttributes.get(ALT_VIS_REPRESENTATION_ATTRIBUTE);
            }
            if (visual_representation == null) {
              visual_representation = "";
            } else {
              ArrayList<String> pictures = getPicturesFromString(visual_representation);
              if (!pictures.isEmpty()) {
                visual_representation = pictures.get(0);
              }
            }
            String description = (String) entityAttributes.get(DESCRIPTION_ATTRIBUTE);
            EntityAttribute ea = new EntityAttribute(name, type, uri, visual_representation, description);
            ArrayList<EntityAdditionalAttribute> addAttrs = getAdditionalAttributes(entityAttributes, ea);
            ea.setEntityAdditionalAttributes(addAttrs);
            retList.add(ea);
          }
        } catch (Exception e) {
          if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
            String msg = "Unable to parse received dictionary entity.";
            Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg, e);
          }
        }
      }  // for each entity
      
    } catch (Exception e) {
      if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
        String msg = "Unable to parse received JSON string with dictionary entities.";
        Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg, e);
      }
      return retList;
    }
    
    return retList;
  }  // getResultFromSECAPI()
  
  /**
   * Creates request to SEC API
   * 
   * @param request Request from client that will be searched
   * @return Returns request for SEC API
   */
  private String createGERequest(EntityRequest request) {
    StringBuilder result = new StringBuilder();
    result.append("{\"get_entities\":{");
    
    result.append("\"input_string\": \"");
    result.append(request.getFilter());
    result.append("\",");
    
    result.append("\"types_and_attributes\": {");
    
    
    // determine which types should be available for entity autocomplete
    ArrayList<SecApiReqTypeDef> available = null;
    if (AppBean.getReqTypeDefinitionsEA() != null && !AppBean.getReqTypeDefinitionsEA().isEmpty()) {
      available = AppBean.getReqTypeDefinitionsEA();
    } else {
      available = AppBean.getAvTypeDefinitions();
    }
    
    // select requested types or all
    ArrayList<SecApiReqTypeDef> requested = new ArrayList<SecApiReqTypeDef>();
    String requestedType = request.getType();
    requestedType.replace(AppBean.getBaseTypeUri(), "");  // remove base URI
    if (requestedType != null && !requestedType.isEmpty() 
        && requestedType.startsWith("*") && requestedType.endsWith("*")) {
      requestedType = requestedType.substring(1, requestedType.length() - 1);
      Iterator<SecApiReqTypeDef> avIt = available.iterator();
      while (avIt.hasNext()) {
        SecApiReqTypeDef td = avIt.next();
        if (td.getTypeName().contains(requestedType) && !Constants.FORBIDDEN_ENTITY_TYPES.contains(td.getTypeName())) {
          requested.add(td);
        }
      }
    } else if (requestedType != null && !requestedType.isEmpty() && requestedType.endsWith("*")) {
      requestedType = requestedType.substring(0, requestedType.length() - 1);
      Iterator<SecApiReqTypeDef> avIt = available.iterator();
      while (avIt.hasNext()) {
        SecApiReqTypeDef td = avIt.next();
        if (td.getTypeName().startsWith(requestedType) && !Constants.FORBIDDEN_ENTITY_TYPES.contains(td.getTypeName())) {
          requested.add(td);
        }
      }
    } else if (requestedType != null && !requestedType.isEmpty() && requestedType.startsWith("*")) {
      requestedType = requestedType.substring(1, requestedType.length());
      Iterator<SecApiReqTypeDef> avIt = available.iterator();
      while (avIt.hasNext()) {
        SecApiReqTypeDef td = avIt.next();
        if (td.getTypeName().endsWith(requestedType) && !Constants.FORBIDDEN_ENTITY_TYPES.contains(td.getTypeName())) {
          requested.add(td);
        }
      }
    } else if (requestedType != null && !requestedType.isEmpty()) {
      Iterator<SecApiReqTypeDef> avIt = available.iterator();
      while (avIt.hasNext()) {
        SecApiReqTypeDef td = avIt.next();
        if (td.getTypeName().contentEquals(requestedType) && !Constants.FORBIDDEN_ENTITY_TYPES.contains(td.getTypeName())) {
          requested.add(td);
        }
      }
    } else {
      Iterator<SecApiReqTypeDef> avIt = available.iterator();
      while (avIt.hasNext()) {
        SecApiReqTypeDef td = avIt.next();
        if (!Constants.FORBIDDEN_ENTITY_TYPES.contains(td.getTypeName())) {
          requested.add(td);
        }
      }
    }
    
    if (requestInfo.getSession().getProtocolLOD() >= Constants.PROTOCOL_LOD_V2 
        && AppBean.getReqTypeDefinitionsEA() != null && !AppBean.getReqTypeDefinitionsEA().isEmpty()) {
      Iterator<SecApiReqTypeDef> reqIt = requested.iterator();
      if (reqIt.hasNext()) {  // first entry
        SecApiReqTypeDef r = reqIt.next();
        result.append(r.getRequestString());
      }
      while (reqIt.hasNext()) {
        result.append(",");
        SecApiReqTypeDef r = reqIt.next();
        result.append(r.getRequestString());
      }
    } else {
      Iterator<SecApiReqTypeDef> reqIt = requested.iterator();
      if (reqIt.hasNext()) {  // first entry
        SecApiReqTypeDef r = reqIt.next();
        result.append(r.getRequestString(REQUESTED_ATTRIBUTES));
      }
      while (reqIt.hasNext()) {
        result.append(",");
        SecApiReqTypeDef r = reqIt.next();
        result.append(r.getRequestString(REQUESTED_ATTRIBUTES));
      }
    }
    
    result.append("},");
    
    Integer maxResults = MAX_RESULTS;
    Object[] paramsP = {"name", Constants.MAX_ENTITIES_SETTINGS_NAME};
    @SuppressWarnings("unchecked")
    List<ServerSetting> settingsList = AppBean.getPersistenceManager().queryDB("ServerSetting.findByName", paramsP);
    if (settingsList != null && !settingsList.isEmpty()) {
      if (!settingsList.get(0).getSettingValue().isEmpty()) {
        try {
          maxResults = Integer.parseInt(settingsList.get(0).getSettingValue());
        } catch (Exception e) {
          maxResults = MAX_RESULTS;
        }
      }
    }

    // if user has specified maximum number of results 
    // this can be only used in protocol version 2 or higher
    if(requestInfo.getSession().getProtocolLOD() >= Constants.PROTOCOL_LOD_V2){
      if(request.getMaxResults() != null && request.getMaxResults() != -1){
        maxResults = request.getMaxResults();

        //applying reserve
        maxResults = (int)Math.round((double)maxResults * (1.0 + Constants.SEC_API_AUTOCOMPLETE_RESULTS_RESERVE / 100.0));
      }
    }

    result.append("\"max_results\": ");
    result.append(maxResults.toString());
    
    result.append("}}");
    return result.toString();
  }  // createGERequest()
  
  /**
   * Makes SEC API request and return result
   * 
   * @param request Request from client that will be searched
   * @return Returns result from SEC API
   */
  private String makeSECAPIRequest(EntityRequest request) {
    
    String secApiRequest = createGERequest(request);
    String SECAPIResults = "";
    
    Boolean processed = false;
    try {
      SECAPIInterface sai = AppBean.getSecApiInterface();
      SECAPIResults = sai.makeRequest(secApiRequest);
      processed = true;
    } catch (Exception ex) {
      String message = "SEC API call error : " + ex.getMessage();
      Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, message);
    }

    // Second attempt
    if (SECAPIResults == null || SECAPIResults.isEmpty()) {
      try {
        SECAPIInterface sai = AppBean.getSecApiInterface();
        // restart SEC API before process
        sai.close();
        if (!sai.init()) {
          Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, "Initialisation of SEC API failed!");
          return SECAPIResults;
        }
        // it is possible that we have updated version of SEC API now
        // (old version was killed and new was started now)
        SuggestionManager.initReqTypes();
        if (AppBean.getReqTypeDefinitions().isEmpty()) {
          return SECAPIResults;
        }
        // update request data
        secApiRequest = createGERequest(request);
        // process request
        SECAPIResults = sai.makeRequest(secApiRequest);
        processed = true;
      } catch (Exception ex) {
        String message = "SEC API call error : " + ex.getMessage();
        Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, message);
        return SECAPIResults;
      }
    }
    
    return SECAPIResults;
  }  // makeSECAPIRequest();
  
  /**
   * Makes remote SEC API request and return result
   * 
   * @param request Request from client that will be searched
   * @return Returns result from SEC API
   */
  private String makeRemoteSECAPIRequest(EntityRequest request) {
    
    String secApiRequest = "";
    String SECAPIResults = "";
    
    try {
      SECAPIConn sac = new SECAPIConn();
      // it is possible that SEC API was updated after last request
      // (old version was killed and new was started) so we need to refresh types
      SuggestionManager.initReqTypesFromRemote(sac, null);
      if (AppBean.getReqTypeDefinitions().isEmpty()) {
        return SECAPIResults;
      }
      // create request data
      secApiRequest = createGERequest(request);
      // process request
      SECAPIResults = sac.sendReqToSECAPI(secApiRequest, null);
    } catch (Exception ex) {
      String message = "Remote SEC API call error : " + ex.getMessage();
      Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, message);
    }
    
    return SECAPIResults;
  }  // makeRemoteSECAPIRequest();
  
  /**
   * Checks if JSON from SEC API contains exception and if yes, logs it
   * 
   * @param jsonData JSON data from SEC API
   * @return If exception was presented, returns true, false otherwise
   */
  private boolean checkException(JSONObject jsonData) {
    String exceptionData = null;
    try {  // try to get exception
      exceptionData = (String) jsonData.get("exception");
    } catch (Exception e) {  // error never mind here
    }
    if (exceptionData != null && !exceptionData.isEmpty()) {
      if (Constants.LOG_LEVEL >= Constants.LOG_LEVEL_SERVER_ERRORS) {
        String msg = "SEC API returned exception: " + exceptionData;
        Logger.getLogger(SECDInterfaceThread.class.getName()).log(Level.SEVERE, msg);
      }
      return true;
    }
    return false;
  }
  
  /**
   * Gets pictures from string
   * 
   * @param string string with pictures
   * @return list of strings
   */
  private ArrayList<String> getPicturesFromString(String string){
    ArrayList<String> result = new ArrayList<String>();
    String[] values = string.split(MULTIPLE_DATA_SEPARATOR,-1);
    
    String picture = "";
    for(int i = 0; i < values.length; i++){
      String[] tmpVal = (values[i]).split("\\.",-1);
      picture += values[i];
      if(tmpVal.length > 1){
        String tmpStr = tmpVal[tmpVal.length-1];
        Iterator<String> strIt = ALLOWED_POSTFIX.iterator();
        while(strIt.hasNext()){
          if(tmpStr.equals(strIt.next())){
            result.add(picture);
            picture = "";
          }
        }
      }
    }
    return result;
  }
  
  /**
   * Parses additional attributes of entity from SEC API
   * 
   * @param entityAttributes JSON object with entity
   * @param parentAttr Entity attribute of annotation to which additional attributes belongs
   * @return Returns array of additional attributes
   */
  ArrayList<EntityAdditionalAttribute> getAdditionalAttributes(JSONObject entityAttributes, EntityAttribute parentAttr){
    ArrayList<EntityAdditionalAttribute> result = new ArrayList<EntityAdditionalAttribute>();
    SecApiReqTypeDef pattern = new SecApiReqTypeDef(parentAttr.getName());
    Integer index = null;
    if (AppBean.getDesTypeDefinitionsEA() != null) {
      index = AppBean.getDesTypeDefinitionsEA().indexOf(pattern);
    }
    SecApiReqTypeDef priorities = null;
    if (index != null && index >= 0) {
      priorities = AppBean.getDesTypeDefinitionsEA().get(index);
    }
    Set keys = entityAttributes.keySet();
    Iterator keysIt = keys.iterator();
    while(keysIt.hasNext()){
      String actualKey = (String) keysIt.next().toString();
      if(!actualKey.equals(URI_ATTRIBUTE) && !actualKey.equals(VIS_REPRESENTATION_ATTRIBUTE) 
              && !actualKey.equals(ALT_VIS_REPRESENTATION_ATTRIBUTE) && !actualKey.equals(DESCRIPTION_ATTRIBUTE) 
              && !NAME_ATTRIBUTES.contains(actualKey)){
        
        String value = (String)entityAttributes.get(actualKey);
        
        EntityAdditionalAttribute newAdditionalAttr = new EntityAdditionalAttribute();
        newAdditionalAttr.setName(actualKey);
        if (actualKey.endsWith("_uri") || actualKey.endsWith("_url") || actualKey.endsWith("ulan_id")) {
          // unreliable hotfix - should be changed in the future
          newAdditionalAttr.setType("URI");
        }
        newAdditionalAttr.setStringValue(value);
        newAdditionalAttr.setRefEntityAttribute(parentAttr);
        if (priorities != null) {
          newAdditionalAttr.setPriority(priorities.getPriority(actualKey));
        }
        
        result.add(newAdditionalAttr);
      }
    }
    
    return result;
  }  // getAdditionalAttributes()
  
}  // public class SECDInterfaceThread