Constructor Detail

• LinkingService

  public LinkingService()

Method Detail

• customizeScopes

  protected void customizeScopes​(Collection<ContainerScope> scopes,
                                 ApplicationArtifact artifact,
                                 ApplicationArtifact container)

  Refines the available container scopes, given the artifact source of the linking and the container.

  The list of container scopes contains entries for associated containers and link types corresponding to the associations. This list is already filtered based on the given linking type, if any.

  This implementation does nothing, i.e. not filtering out anything from the list. Subclasses may override to restrict the link types, for example if some of them are disabled at server administration level. Implementation should also override getCustomizedScopesFeedback(LinkingType, ApplicationArtifact, ApplicationArtifact) in this case.

  Parameters:

  scopes - the available container scopes and their link types.

  artifact - the artifact source of the linking.

  container - the local container owning the artifact.

• getCustomizedScopesFeedback

  protected Optional<Feedback> getCustomizedScopesFeedback​(LinkingType linkingType,
                                                           ApplicationArtifact artifact,
                                                           ApplicationArtifact container)

  Gets a feedback to explain why a given linking type was excluded from the scopes.

  This implementation returns Optional.empty(), as no scope customization is done as a default. Implementations overriding customizeScopes(Collection, ApplicationArtifact, ApplicationArtifact) should also override this method to provide a detailed reason of the exclusion.

  Parameters:

  linkingType - the given linking type.

  artifact - the local linking artifact.

  container - the local linking artifact container.

  Returns:

  a feedback instance, or Optional.empty() if no details on the customized scopes.

  Since:

  3.5.0

• getScope

  public Response getScope​(String containerId,
                           String artifactId,
                           String artifactType)

  Resolves the link types (or domains) available for linking per remote associated project.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  the link types (or domains) available for linking if they exist; a suitable feedback otherwise.

  Throws:

  OslcWebApplicationException - (bad request) if any parameter is null.
  (not found) if either the native container or artifact are not available.
  (forbidden) if the logged-in user cannot edit the native artifact for linking.
  (server error) if the corresponding remote associations cannot be loaded.

• getScopeExplanation

  public Response getScopeExplanation​(String containerId,
                                      String artifactId,
                                      String artifactType)

  Explains with Feedback messages why a given link type (or domain) is available (or not) for linking.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  a Feedback with messages detailing the scope.

  Throws:

  OslcWebApplicationException - (bad request) if any parameter is null.
  (not found) if either the native container or artifact are not available.
  (forbidden) if the logged-in user cannot edit the native artifact for linking.
  (server error) if the corresponding remote associations cannot be loaded.

• getSupportedLinkingTypes

  public Response getSupportedLinkingTypes​(String containerId,
                                           String artifactId,
                                           String artifactType)

  Responds all link types that are supported by the application, independently of friends and project associations. The given artifact information is used to resolve the corresponding standard OSLC type, to determine the applicable link types.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  the link types supported by the application for the given type of artifact.

  Throws:

  OslcWebApplicationException - (bad request) if any parameter is null.
  (not found) if either the native container or artifact are not available.

  Since:

  3.5.0

• postScope

  public Response postScope​(String containerId,
                            String artifactId,
                            String artifactType)

  Determines the link types (or domains) available for linking given the linking resources (dropped/pasted elements).

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  the link types (or domains) available for the linking resources.

  Throws:

  OslcWebApplicationException - (bad request) if any parameter is null or no association can be resolved for the linking resources.
  (precondition failed) if an association is found but link types were disabled on the hosting application
  (server error) if the corresponding remote associations cannot be loaded.

• validateScope

  public Response validateScope​(String containerId,
                                String artifactId,
                                String artifactType)

  Evaluates a potential remote artifact URL against a previously-chosen linking scope.

  This method is used to assert a dropped or pasted artifact belongs or is compatible with the chosen linking scope.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  the oslc:Compact representation of the linkingResource with no Feedback if the validation succeeded (which means the linking from artifactId to LinkingResource is possible. An error feedback indicates the linking is not possible and a warning feedback means the linking is possible but some (GlobalConfiguration) issues may exists.

  Throws:

  OslcWebApplicationException - (bad request) if any parameter (but the AbstractLinkingContext.getConfiguration() is null (bad request) if the AbstractLinkingContext.getLinkingType() is unknown.
  (bad request) if the linkingResource is not a URL.
  (bad request) if the linkingResource does not correspond to an OSLC linkable resource.
  (not found) if either the native container or artifact are not available.
  (forbidden) if the logged-in user cannot edit the native artifact for linking.
  (server error) if the corresponding remote associations cannot be loaded.
  (server error) if a remote communication fails.

• customizeDialogs

  protected void customizeDialogs​(List<Service> services,
                                  LinkingType linkingType,
                                  ApplicationArtifact artifact,
                                  ApplicationArtifact container)

  Refines the available services' dialogs, given the artifact source of the linking and the container.

  The list of services are already filtered to the linking domain and linking range if any. This implementation does nothing, i.e. not filtering out anything from the list. Subclasses may override to add filtering criteria, for example if a dialog for a given resource type is not allowed.

  Parameters:

  services - the available services and their dialogs.

  linkingType - the linking type.

  artifact - the artifact source of the linking.

  container - the local container owning the artifact.

• getCustomizedDialogCause

  protected Optional<String> getCustomizedDialogCause​(LinkingType linkingType,
                                                      ApplicationArtifact artifact,
                                                      ApplicationArtifact container,
                                                      boolean isCreationDialog)

  Gets the cause to explain why a given type of dialog was excluded from the scopes.

  This implementation returns an empty optional. Subclasses may override to get the filtering criteria cause.

  Parameters:

  linkingType - the given linking type.

  artifact - the local linking artifact.

  container - the local linking artifact container.

  isCreationDialog - whether the excluded dialog of interest if the creation dialog or not.

  Returns:

  an empty Optional if no cause is provided, the contained cause otherwise.

• getTarget

  public Response getTarget​(String containerId,
                            String artifactId,
                            String artifactType,
                            URI linkingType,
                            URI remoteServiceProvider,
                            URI configuration,
                            String configurationTitle)

  Fetches the remote linking service provider (in the context of a GC if any) while scoping the dialogs to the linking type.

  An in-use global configuration can be provided by the hosting application if applicable (typically if there's a GC picker widget); otherwise, this end point will try to resolve the indirect-in-use global configuration if any.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  linkingType - the linking type.

  remoteServiceProvider - the remote ServiceProvider.

  configuration - the (optional) in-use global configuration URI.

  configurationTitle - the (optional) in-use global configuration title.

  Returns:

  the remote linking service provider.

  Throws:

  OslcWebApplicationException - (bad request) if a non-optional parameter is null or the linking type is unknown.
  (not found) if either the native container or artifact are not available.
  (forbidden) if the logged-in user cannot edit the native artifact for linking.
  (server error) if a remote communication fails.

• createLocalLink

  protected abstract void createLocalLink​(ApplicationArtifact artifact,
                                          ApplicationArtifact container,
                                          LinkingType linkingType,
                                          Link remoteResource,
                                          ConfigContext configuration,
                                          HttpServletRequest request)

  Creates/saves the local link when suitable. This method is called ONLY when saving locally has meaning for the linking type nature.

  Parameters:

  artifact - the local linking artifact.

  container - the local linking artifact container.

  linkingType - the linking type to be created.

  remoteResource - the remote (target) resource.

  configuration - the in-use global configuration, if any.

  request - the current HTTP request.

• link

  public Response link​(String containerId,
                       String artifactId,
                       String artifactType)

  Creates (if applicable) a remote incoming link and (if applicable) a local outgoing link.

  Parameters:

  containerId - the native linking artifact container Id.

  artifactId - the native linking artifact Id.

  artifactType - the linking artifact type, see ApplicationArtifact.

  Returns:

  a success response.

  Throws:

  OslcWebApplicationException - (bad request) if a non-optional parameter is null or the linking type is unknown.
  (not found) if either the native container or artifact are not available.
  (forbidden) if the logged-in user cannot edit the native artifact for linking.
  (server error) if a remote communication fails.

• getMissingCompactInContextHint

  protected Optional<String> getMissingCompactInContextHint​(URI compact,
                                                            ApplicationArtifact artifact,
                                                            ApplicationArtifact container,
                                                            LinkingType linkingType)

  Provides a hint to solve the missing-compact-in-context issue.

  Applications can override this method to guide users on how to solve the issue.

  Parameters:

  compact - the missing compact URI.

  artifact - the local linked artifact.

  container - the local linked artifact container.

  linkingType - the link type

  Returns:

  an empty Optional if no guide is available; the contained hint otherwise.

  Since:

  3.3.0

• getMissingLinkContextWarningMessage

  protected String getMissingLinkContextWarningMessage​(Compact compact,
                                                       ApplicationArtifact artifact,
                                                       ApplicationArtifact container,
                                                       LinkingType linkingType)
                                                throws Exception

  Gets the missing context warning message for a linked artifact.

  This message warns users about a possibly missing GC when fetching Compact resources of linked artifacts.

  Applications can override this method to provide a more detailed message than the generic one.

  Parameters:

  compact - the remote Compact resource.

  artifact - the local linked artifact.

  container - the local linked artifact container.

  linkingType - the link type

  Returns:

  No Global Configuration is being used for this link. However, one may be required given the nature of the associated projects. Please validate whether the artifact version is the expected one or make sure a proper Global Configuration is used.

  Throws:

  Exception - if any exception occurs trying build the appropriate message.

  Since:

  3.3.0

• getLinkCompact

  public Response getLinkCompact​(URI link,
                                 URI linkingType,
                                 String containerId,
                                 String artifactId,
                                 String artifactType)
                          throws ServletException,
                                 IOException

  Resolves the Compact resource of a linked artifact.

  Unlike ProxyService.getCompact(String), this method is aimed to provide guidance and feedback to users when there is, or there may be, a Global Configuration issue. Applications can override getMissingCompactInContextHint(URI, ApplicationArtifact, ApplicationArtifact, LinkingType) and/or getMissingLinkContextWarningMessage(Compact, ApplicationArtifact, ApplicationArtifact, LinkingType) to provide a more detailed hint/guidance.

  Parameters:

  link - the remote resource URI.

  linkingType - the linking type.

  containerId - the local artifact container id.

  artifactId - the local artifact id.

  artifactType - the local artifact type.

  Returns:

  the Compact representation of the remote resource.

  Throws:

  ServletException - if request cannot be dispatched to a local resource.

  IOException - if some I/O exception occurs.

  Since:

  3.3.0

• getOslcUri

  public Response getOslcUri​(String url)