• Home
• com.echobox
• ebx-linkedin-sdk
• 4.0.0
• source code
• OrganizationConnection.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

com.echobox.api.linkedin.connection.v2.OrganizationConnection Maven / Gradle / Ivy

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 com.echobox.api.linkedin.connection.v2;

import com.echobox.api.linkedin.client.LinkedInClient;
import com.echobox.api.linkedin.client.Parameter;
import com.echobox.api.linkedin.types.TimeInterval;
import com.echobox.api.linkedin.types.engagement.ShareStatistic;
import com.echobox.api.linkedin.types.organization.AccessControl;
import com.echobox.api.linkedin.types.organization.NetworkSize;
import com.echobox.api.linkedin.types.organization.Organization;
import com.echobox.api.linkedin.types.organization.OrganizationBase;
import com.echobox.api.linkedin.types.organization.OrganizationBrand;
import com.echobox.api.linkedin.types.organization.OrganizationResult;
import com.echobox.api.linkedin.types.statistics.OrganizationFollowerStatistics;
import com.echobox.api.linkedin.types.statistics.page.FollowerStatistic;
import com.echobox.api.linkedin.types.statistics.page.Statistics;
import com.echobox.api.linkedin.types.urn.URN;
import com.echobox.api.linkedin.types.urn.URNEntityType;
import com.echobox.api.linkedin.util.ValidationUtils;
import org.apache.commons.lang3.StringUtils;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * Organization connection class that should contain all organization operations
 * @see
 * 
 * Organization Access Contol
 * 
 * @author joanna
 *
 */

// Ignore CPD as this will be removed after migration
// CPD-OFF
@Deprecated
public class OrganizationConnection extends ConnectionBaseV2 {
  
  private static final String ORGANIZATION_ACLS = "/organizationAcls";
  private static final String ORGANIZATIONS = "/organizations";
  private static final String ORGANIZATIONS_BRANDS = "/organizationBrands";
  private static final String ORGANIZATIONAL_ENTITY_FOLOWER_STATS =
      "/organizationalEntityFollowerStatistics";
  private static final String ORGANIZATIONAL_PAGE_STATS = "/organizationPageStatistics";
  private static final String NETWORK_SIZES = "/networkSizes";
  private static final String SHARE_STATISTICS = "/organizationalEntityShareStatistics";
  
  private static final String ROLE_KEY = "role";
  private static final String STATE_KEY = "state";
  private static final String VANITY_NAME_KEY = "vanityName";
  private static final String EMAIL_DOMAIN_KEY = "emailDomain";
  private static final String ORGANIZATIONAL_ENTITY_KEY = "organizationalEntity";
  private static final String ORGANIZATION_KEY = "organization";
  
  private static final String ROLE_ASSIGNEE_VALUE = "roleAssignee";
  private static final String VANITY_NAME_VALUE = "vanityName";
  private static final String EMAIL_DOMAIN_VALUE = "emailDomain";
  private static final String ORGANIZATIONAL_ENTITY_VALUE = "organizationalEntity";
  private static final String ORGANIZATION_VALUE = "organization";
  private static final String COMPANY_FOLLOWED_BY_MEMEBER = "CompanyFollowedByMember";
  
  private static final String PARENT_KEY = "parent";
  private static final String PARENT_ORGANIZATION_VALUE = "parentOrganization";

  /**
   * Initialise an organization connection
   * @param linkedinClient the linkedIn API client to create a LinkedIn organization connection
   */
  public OrganizationConnection(LinkedInClient linkedinClient) {
    super(linkedinClient);
  }

  /**
   * Find a Member's Organization Access Control Information
   * E.g. https://api.linkedin.com/v2/organizationAcls?q=roleAssignee
   * @see 
   * Access Control
   * @param role Limit results to specific roles, such as ADMINISTRATOR.
   * @param state Limit results to specific role states, such as APPROVED.
   * @param projection Field projection
   * @param count the number of entries to be returned per paged request
   * @return List of access controls for a given role and state for the member
   */
  public List fetchMemberOrganizationAccessControl(String role, String state,
      Parameter projection, Integer count) {
    List params = new ArrayList<>();
    params.add(Parameter.with(QUERY_KEY, ROLE_ASSIGNEE_VALUE));
    addRoleStateParams(role, state, projection, params);
    addStartAndCountParams(params, null, count);
    
    return getListFromQuery(ORGANIZATION_ACLS, AccessControl.class,
        params.toArray(new Parameter[0]));
  }
  
  /**
   * Find an Organization's Access Control Information
   * @see 
   * Access Control
   * @param organizationURN The organization for which access control information
   * is retrieved.
   * @param role Limit results to specific roles
   * @param state Limit results to specific role states
   * @param projection Field projection
   * @param count the number of entries to be returned per paged request
   * @return List of access controls for an organization
   */
  public List findOrganizationAccessControl(URN organizationURN,
      String role,
      String state, Parameter projection, Integer count) {
    validateOrganizationURN("organization", organizationURN);
    
    List parameters = new ArrayList<>();
    parameters.add(Parameter.with(QUERY_KEY, ORGANIZATION_VALUE));
    parameters.add(Parameter.with(ORGANIZATION_KEY, organizationURN.toString()));
    addRoleStateParams(role, state, projection, parameters);
    addStartAndCountParams(parameters, null, count);
    
    return getListFromQuery(ORGANIZATION_ACLS, AccessControl.class,
        parameters.toArray(new Parameter[0]));
  }

  /**
   * Find an organization using an organization ID, parent organization ID
   * @see Retrieve organization
   * @param organizationURN The organization URN
   * @param fields the fields to project
   * @return the requested organization
   */
  public Organization retrieveOrganization(URN organizationURN, Parameter fields) {
    validateOrganizationURN("organizationURN", organizationURN);
    List parameters = new ArrayList<>();
    if (fields != null) {
      parameters.add(fields);
    }
    return linkedinClient.fetchObject(ORGANIZATIONS + "/" + organizationURN.getId(),
        Organization.class, parameters.toArray(new Parameter[0]));
  }

  /**
   * Lookup an organization by vanity name
   * @see 
   * Retrieve organization
   * @param vanityName the vanity name for the organization
   * @param fields the fields to request
   * @param count the number of entries to be returned per paged request
   * @return The organization with the vanity name
   */
  public List findOrganizationByVanityName(String vanityName,
      Parameter fields, Integer count) {
    ValidationUtils.verifyParameterPresence("vanityName", vanityName);
  
    List parameters = new ArrayList<>();
    if (fields != null) {
      parameters.add(fields);
    }
    parameters.add(Parameter.with(QUERY_KEY, VANITY_NAME_VALUE));
    parameters.add(Parameter.with(VANITY_NAME_KEY, vanityName));
    addStartAndCountParams(parameters, null, count);
    List organizationList = getListFromQuery(ORGANIZATIONS,
        OrganizationResult.class, parameters.toArray(new Parameter[0]));
    
    return organizationList.stream().map(OrganizationResult::getOrganization)
        .collect(Collectors.toList());
  }

  /**
   * Lookup an organization by email domain
   * @see 
   * Retrieve organization
   * @param emailDomain the email domain for the organization
   * @param fields the fields to request
   * @param count the number of entries to be returned per paged request
   * @return A list of organizations with the email domain
   */
  public List findOrganizationByEmailDomain(String emailDomain, Parameter fields,
      Integer count) {
    ValidationUtils.verifyParameterPresence("emailDomain", emailDomain);
  
    List parameters = new ArrayList<>();
    if (fields != null) {
      parameters.add(fields);
    }
    parameters.add(Parameter.with(QUERY_KEY, EMAIL_DOMAIN_VALUE));
    parameters.add(Parameter.with(EMAIL_DOMAIN_KEY, emailDomain));
    addStartAndCountParams(parameters, null, count);
    return getListFromQuery(ORGANIZATIONS, Organization.class,
        parameters.toArray(new Parameter[0]));
  }
  
  /**
   * Retrieve the number of first-degree connections (followers) for any organization.
   * @see 
   * Retrieve Organization Follower Count
   * @param organizationURN the organization URN
   * @return the number of followers for the organization
   */
  public Long retrieveOrganizationFollowerCount(URN organizationURN) {
    validateOrganizationOrBrandURN("organizationURN", organizationURN);
    NetworkSize networkSize = linkedinClient.fetchObject(NETWORK_SIZES + "/" + organizationURN,
        NetworkSize.class, Parameter.with(EDGE_TYPE, COMPANY_FOLLOWED_BY_MEMEBER));
    return networkSize.getFirstDegreeSize();
  }

  /**
   * Look up a member's positions and related organization IDs.
   * @see 
   * Find Organizations Associated with a Member's Positions
   */
  public void findOrganizationsAssociatedToMemberPosition() {
    throw new UnsupportedOperationException("Operation is not implemented yet.");
  }

  /**
   * Use organization brand id to find all all of its information
   * @see 
   * Retrieve an organization brand
   * @param organizationBrandURN organizationBrandId
   * @param fields the fields to request
   * @return the organization brand
   */
  public OrganizationBrand retrieveOrganizationBrand(URN organizationBrandURN, Parameter fields) {
    validateOrganizationBrandURN("organizationBrandURN", organizationBrandURN);
    List parameters = new ArrayList<>();
    if (fields != null) {
      parameters.add(fields);
    }
    String id = organizationBrandURN.getId();
    return linkedinClient.fetchObject(ORGANIZATIONS_BRANDS + "/" + id, 
        OrganizationBrand.class, parameters.toArray(new Parameter[0]));
  }

  /**
   * Use organization vanity name to find all all of its information
   * @see 
   * Retrieve Organization Brand by Vanity Name
   * @param vanityName vanity name
   */
  public void retrieveOrganizationBrandByVanityName(String vanityName) {
    throw new UnsupportedOperationException("Operation is not implemented yet.");
  }

  /**
   * Use organization parent URN to get a list of array of brands that belong to the specified
   * parent
   * @see 
   * Retrieve Organization Brand by Parent Organization
   * @param organizationURN parent organization URN
   * @return all the organization brands
   */
  public List retrieveOrganizationBrandByParentOrganization(
      URN organizationURN) {
    validateOrganizationURN("organizationURN", organizationURN);
    
    List parameters = new ArrayList<>();
    parameters.add(Parameter.with(QUERY_KEY, PARENT_ORGANIZATION_VALUE));
    parameters.add(Parameter.with(PARENT_KEY, organizationURN.toString()));
    
    return getListFromQuery(ORGANIZATIONS, OrganizationBrand.class,
        parameters.toArray(new Parameter[0]));
  }

  /**
   * Use organization parent URN to get a list of array of brands that belong to the specified
   * parent
   * @see 
   * Retrieve Organization's Media Content
   * @param organizationId organization id
   */
  public void retrieveOrganizationMediaContent(long organizationId) {
    throw new UnsupportedOperationException("Operation is not implemented yet.");
  }

  /**
   * Search for organizations
   * @param searchTerm the search term
   * @return a list of organizations that match the organization
   */
  public List searchForOrganizations(String searchTerm) {
    throw new UnsupportedOperationException("Operation is not implemented yet.");
  }

  /**
   * Retrieve the lifetime follower statistics. Providing the time interval will retrieve
   * time-bounded follower statistics, otherwise the lifetime follower statistics will be returned
   * @see 
   * Organization Follower Statistics
   * @param organizationURN the organization URN to retrieve the follower statistics
   * @param count the number of entries to be returned per paged request
   * @return a list of organization's follower statistics
   */
  public List retrieveOrganizationFollowerStatistics(
      URN organizationURN, Integer count) {
    validateOrganizationURN("organizationURN", organizationURN);
    List parameters = new ArrayList<>();

    addParametersForStatistics(organizationURN, null, parameters);
    addStartAndCountParams(parameters, null, count);

    return getListFromQuery(ORGANIZATIONAL_ENTITY_FOLOWER_STATS,
        OrganizationFollowerStatistics.class,
        parameters.toArray(new Parameter[0]));
  }
  
  /**
   * Retrieve both lifetime and time-bound statistics on followers for an organization.
   * Lifetime follower statistics: To retrieve lifetime follower statistics, omit the
   * timeIntervals query parameter. The API returns follower counts segmented by various facets
   * such as region and industry.
   *
   * Time-bound follower statistics: To retrieve time-bound follower statistics, include the
   * timeIntervals query parameter. The API returns the aggregate follower count for both paid
   * and organic followers during the days or months of the selected date range, based on the
   * specified timeIntervals.timeGranularityType.
   * @see 
   * Organization Follower Statistics
   * @param organizationURN the organization RUN
   * @param timeInterval the time interval for time bound follower statistics
   * @param count the number of entries to be returned per paged request
   * @return a list of organization follower statistics
   */
  public List retrieveOrganizationFollowerStatistics(URN organizationURN,
      TimeInterval timeInterval, Integer count) {
    validateOrganizationURN("organizationURN", organizationURN);
    
    List parameters = new ArrayList<>();
    
    addParametersForStatistics(organizationURN, timeInterval, parameters);
    addStartAndCountParams(parameters, null, count);
    
    return getListFromQuery(ORGANIZATIONAL_ENTITY_FOLOWER_STATS, FollowerStatistic.class,
        parameters.toArray(new Parameter[0]));
  }

  /**
   * Retrieve the lifetime follower statistics. Providing the time interval will retrieve
   * time-bounded follower statistics, otherwise the lifetime follower statistics will be returned
   * @see 
   * Organization Page Statistics - Lifetime
   * @see 
   * Organization Page Statistics - time-bound
   * @param organizationURN the organization URN to retrieve the page statistics
   * @param timeInterval the time interval  for time-bound follower statistics
   * @param count the number of entries to be returned per paged request
   * @return a list of organization's follower statistics
   */
  public List retrieveOrganizationPageStatistics(
      URN organizationURN, TimeInterval timeInterval, Integer count) {
    validateOrganizationURN("organizationURN", organizationURN);

    List parameters = new ArrayList<>();
    parameters.add(Parameter.with(QUERY_KEY, ORGANIZATION_VALUE));
    parameters.add(Parameter.with(ORGANIZATION_KEY, organizationURN.toString()));

    addTimeIntervalToParams(parameters, timeInterval);
    addStartAndCountParams(parameters, null, count);

    return getListFromQuery(ORGANIZATIONAL_PAGE_STATS, Statistics.OrganizationStatistics.class,
        parameters.toArray(new Parameter[0]));
  }

  /**
   * Retrieve organization brand page statistics
   * @see 
   * Organization Brand Page Statistics
   * @see 
   * Organization Brand Page Statistics - time-bound
   * @param organizationBrand the organization brand URN
   * @param timeInterval the time interval for time bounded statistics
   * @return list of page statistics for the organization brand
   */
  public List retrieveOrganizationBrandPageStatistics(
      URN organizationBrand, TimeInterval timeInterval) {
    throw new UnsupportedOperationException("Operation is not implemented yet.");
  }
  
  /**
   * retrieve both lifetime and time-bound organic statistics on shares for an organization,
   * including specific organization share URNs. This endpoint returns organic statistics only.
   * Sponsored activity is not counted in this endpoint.
   * @see 
   * Organization Share Statistics
   * @param organizationURN the organizational entity URN for which the statistics represents
   * @param timeInterval Time restriction for the query. When omitted, lifetime stats are returned
   * @param shareURNs References to one or more shares for which statistics are returned
   * @param count the number of entries to be returned per paged request
   * @return aggregated stats for an organization's shares
   */
  public List retrieveShareStatistics(URN organizationURN,
      TimeInterval timeInterval, List shareURNs, Integer count) {
    validateOrganizationOrBrandURN("organizationURN", organizationURN);
    
    List params = new ArrayList<>();
    params.add(Parameter.with(QUERY_KEY, ORGANIZATIONAL_ENTITY_KEY));
    params.add(Parameter.with(ORGANIZATIONAL_ENTITY_KEY, organizationURN));
    
    if (shareURNs != null && !shareURNs.isEmpty()) {
      shareURNs.forEach(this::validateShareURN);
      addParametersFromURNs(params, SHARES_PARAM, shareURNs);
    }
  
    addTimeIntervalToParams(params, timeInterval);
    addStartAndCountParams(params, null, count);
    
    return getListFromQuery(SHARE_STATISTICS, ShareStatistic.class,
        params.toArray(new Parameter[0]));
  }
  
  private void validateOrganizationOrBrandURN(String paramName, URN organizationOrBrandURN) {
    ValidationUtils.verifyParameterPresence(paramName, organizationOrBrandURN);
    if (!(URNEntityType.ORGANIZATION.equals(organizationOrBrandURN.resolveURNEntityType())
        || URNEntityType.ORGANIZATIONBRAND.equals(organizationOrBrandURN.resolveURNEntityType()))) {
      throw new IllegalArgumentException(String.format("The URN should be type %s or %s",
          URNEntityType.ORGANIZATION, URNEntityType.ORGANIZATIONBRAND));
    }
  }

  private void validateOrganizationURN(String paramName, URN organizationURN) {
    validateURN(paramName, organizationURN, URNEntityType.ORGANIZATION);
    ValidationUtils.verifyParameterPresence(paramName, organizationURN);
    validateURN(URNEntityType.ORGANIZATION, organizationURN);
  }
  
  private void validateOrganizationBrandURN(String paramName, URN organizationBrandURN) {
    validateURN(paramName, organizationBrandURN, URNEntityType.ORGANIZATIONBRAND);
  }
  
  private void validateURN(String paramName, URN urn, URNEntityType type) {
    ValidationUtils.verifyParameterPresence(paramName, urn);
    validateURN(type, urn);
  }
  
  private void addRoleStateParams(String role, String state, Parameter projection,
      List parameters) {
    if (StringUtils.isNotBlank(role)) {
      parameters.add(Parameter.with(ROLE_KEY, role));
    }
    if (StringUtils.isNotBlank(state)) {
      parameters.add(Parameter.with(STATE_KEY, state));      
    }
    if (projection != null) {
      parameters.add(projection);
    }
  }
  
  private void addParametersForStatistics(URN organizationURN, TimeInterval timeInterval,
      List parameters) {
    validateOrganizationURN("organizationURN", organizationURN);

    parameters.add(Parameter.with(QUERY_KEY, ORGANIZATIONAL_ENTITY_VALUE));
    parameters.add(Parameter.with(ORGANIZATIONAL_ENTITY_KEY, organizationURN.toString()));

    addTimeIntervalToParams(parameters, timeInterval);
  }

}